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PREFACE 


This manual is the primary reference for using the IRMX 86 Human 
Interface software on your IRMX 86 Operating System. The manual Is 
addressed to two levels of users: 

• Operators who will be using Intelnsupplled Human Interface 
commands and (optionally) user-created commands at the console 
keyboard* 

• Development programmers who will be writing custom application 
progams that can be loaded and executed via Interactive keyboard 
commands • 

The manual Is lnp licit ly divided Into two general sections that 
approximate these two Human Interface user-levels: 

1. Chapters 1 through 4 are addressed to all levels of readers and 
describe the syntax, format, and uses of the supplied Human 
Interface commands: 

• Chapter 1 Introduces you to the purpose and scope of the 
Human Interface* 

• Chapter 2 describes the general syntax rules and other 
considerations for using Interactive commands to load and 
execute programs during your console sessions* 

• Chapter 3 describes the function and syntax of Human 
Interface commands, plus the Interactive system pronpts and 
user responses that take place during command execution* 

• Chapter 4 provides a series of Human Interface command 
exanqples that Introduce the console user to basic IRMX 86 
file management* 

2. Chapters 5 through 7 are addressed to the programmer who will be 
writing new application commands that can be executed from the 
console keyboard under the control of the Human Interface: 

• Chapter 5 describes some of the programming considerations 
for using Human Interface system calls In a program’s source 
code* 

• Chapter 6 describes the Human Interface system calls In 
alphabetical sequence* A system call dictionary Is provided 
at the beginning of the chapter for fast reference* 
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PREFACE (continued) 


• Chapter 7 provides an example of how Human Interface calls 
are used to create a new command. 

• Appendixes A, B, and C describe the Human Interface type 
definitions, exception codes, and string table format, 
respectively. 


RELATED PUBLICATIONS 

The following manuals provide additional background and reference 
information: 

Manual Number 

Introduction to the iRMK 86” Operating System 9803124 

iRMX 86” Nucleus Reference Manual 9803122 

iRMX 86” Terminal Handler Reference Manual 143324 

iRMX 86” Basic I/O System Reference Manual 9803123 

iRMX 86” Extended I/O System Reference Manual 143308 

iRMX 86” Loader Reference Manual 143318 

iRMX 86” System Programmer’s Reference Manual 142721 

iRMX 86” Configuration Guide 9803126 

iRMX 86” Programming Techniques 142982 

IRMX 86” Disk Verficatlon Utility Reference Manual 144i33 

8086 Family Utilities User's Guide for 8080/8085-Based 

Development Systems 9800639 

lAPX 86,88 Family Utilities Users* Guide for 8086-Based 

Development Systems 121616 

Users* Guide for the ISBC 957B” iAPX 86,88 Interface and 

Execution Package 143979 

Guide to Writing Device Drivers for the IRMX 86” and 

iRMX 88” I/O Systems 142926 

IMMX 800 Software Reference Manual and User's Guide 143808 
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CHAPTER 1. INTRODUCTION 


The iRMX 86 Human Interface allows console operators to load and execute 
program files from a console keyboard. The operator types a command name 
that is the name of the application program to be executed. That program 
is loaded into main memory from secondary storage and the program is 
executed in conformance with any required or optional parameters that the 
operator specified in the command line. 

The console operator and the Human Interface begin an interactive dialog 
once a command is typed. A Human Interface module called the Command 
Line Interpreter (CL I) scans the command line for validity and then 
executes the associated program. If any syntax or other errors are 
detected in the command entry, an explanatory error message is displayed 
on the console screen and the operator is prompted for a new command 
entry. 

During execution, further dialog between the console operator and the 
program itself may take place if the program encounters specifications in 
the command line that require further clarification. The program then 
prompts the operator for a course of action it is to follow. Generally, 
such queries are issued because a command line parameter is subject to 
ambiguous interpretation, or to protect existing program or data file 
structures from accidental destruction or modification. The displayed 
prompts and queries are coded into the program via Human Interface system 
calls when the program is written. 

When program execution is completed, a status message is displayed that 
defines what actlon(s) the program performed. The Human Interface then 
prompts for a new command entry. Thus, program execution is truly 
Interactive, from the time the operator enters a command until execution 
is completed. The operator controls and sometimes modifies execution 
through command parameter entries and keyboard responses to prompts 
Issued by the program. Human Interface functions, in turn, respond to 
the operator keyboard entries by displaying status messages, error 
messages or prompts to ensure successful program operation. 


HUMAN INTERFACE SOFTWARE REQUIREMENTS 


The Human Interface functions can be used on any IRMX 86 Operating System 
that is configured with all of the following software layers: 

• Nucleus 

• Basic I/O System 

• Extended I/O System 
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• Application Loader 

• Human Interface 

The Human Interface is a software layer in an iRMX 86 Operating System 
that is configured with the above-named modules* During command 
execution, the Human Interface invokes the services of these software 
modules in a way that is transparent to the console operator. Therefore, 
an operator needs little or no knowledge of operating system structures 
to load and execute programs from the console keyboard. 


HUMAN INTERFACE SERVICES 


The Human Interface provides and supports two distinct levels of services 
for iRMX 86 users: 

1. A set of non-resident Human Interface commands that consist of 
file management and general utility routines. These commands are 
available for immediate use on any IRMX 86 Operating System that 
is configured with the Human Interface. The Human Interface 
commands are described in detail in Chapters 3 and 4 of this 
manual. 

2. A set of system calls that provides programmers with convenient 
routines for creating new applications commands. This feature is 
of particular value to OEM’s who are writing custom IRMX 86 
applications for their own customers. The programmer Invokes 
specific command handling functions associated with the new 
program by including the relevant Human Interface calls in the 
program’s source code. 

Once a new command is assembled and linked, the programmer stores 
it either under the :PROG: directory in secondary storage, or 
under the : SYSTEM: directory for debugged commands (see "Supplied 
Directories" later in this chapter for a description of the 
:PROG: and : SYSTEM: directories). The Human Interface calls are 
described in Chapters 5 and 6. 

All iRMX 86 Nucleus, I/O System, Extended I/O System, and 
Application Loader calls are also available when writing an 
application program associated with a user-designed command. See 
the appropriate iRMX 86 reference manuals. 

Both the Intel-supplied and user-created commands should use the same 
general syntax. This consistency in syntax makes it easier for the 
console operator to use commands at the keyboard and aids the system 
programmer who is designing and creating new commands. 
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HUMAN INTERFACE COMMAND SET FEATURES 

Some of the main features provided by the Intel-supplied file handling 
and utility routines are described in the following list. The console 
operator can invoke any of the services by entering a single command; 

• Create a new file. 

• Create new directories. 

• List the contents of a file. 

• List a directory, plus the attributes of all files in the 
directory. Five listing formats are availaible, depending upon 
the amount of information desired. 

• Rename files or directories across directory boundaries. 

• Delete files and/or directories. 

• Append one or more files to the end of an existing file, or 
concatenate files. 

• Copy files from an ISIS-II volume mounted on a secondary storage 
device to an IRMX volume mounted on a secondary storage device, 
or vice versa. 

• Read command input from a secondary storage device. 

• Format a new volume. 

• Set or reset the system date and time from the console keyboard. 


HUMAN INTERFACE SYSTEM CALL FEATURES 

The Human Interface system calls let programmers create new commands that 
are compatible with the standard syntax. The calls consist of command 
parsing, processing, and I/O connection routines that link an application 
program with iRMX 86 Operating System resources in a way that is 
completely transparent to the operator during command execution. 

Optional parameter elements in the calls give the programmer the ability 
to create new commands that are tailored to the exact requirements of the 
end user. An important feature of the calls is that they ensure a 
consistent syntax and processing for new commands. Thus, user-created 
commands will still be usable without modification or rewriting in future 
releases of the Human Interface. 

Some of the main services provided by the Human Interface system calls 
are as follows; 

• Define the location of the user’s system console input and output 
devices (;CI; and ;C0; , which are described later in the manual). 
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• Set up I/O connections to input and output files specified in a 
command line. 

• Set up a command connection to send multiple-line commands. 

• Allow a user to obtain control of the CTRL/C key. 

• Concatenate multiple-line commands and then execute the command. 

• Format a default message for a given exception code. 

• Send and receive messages to and from the user’s console. 


FILE AND DIRECTORY STRUCTURES 


The following subsections in this chapter define the file organization 
and structures used both by the console operator and by executing 
programs . 


FILES 

The file is the basic unit in the file organization. A file has a 
pathname by which it is accessed, and it resides on a volume of some 
secondary storage device rather than in main memory (see the pathname 
definition under the next heading). A named file may consist of data 
accessed by one or more programs, data that you access at the console, a 
directory, or an executable program file that you invoke by a Human 
Interface command. For example, all the supplied Human Interface 
commands are non-resident program files. 


PATHNAME 


A pathname is a "road map" through the hierarchical tree structure for a 
named file or directory that is to be accessed during command execution. 
This pathname tells the excuting command which directories (and in some 
cases which device; see "Volumes" in this chapter) to search to find the 
desired file or directory. 

When you list a pathname in a command entry, enter each name element 
within the path in a descending hierarchical order, and separate each of 
these pathname elements with a slash mark (/). For example: 

: F 1 : PRIME /L E VEL A/ my t e s t 

is the pathname for a file named "iiiytest" which is located on a volume 
mounted on a device whose prefix is ;Fl:. PRIME/LEVELA means the 
command is to search a parent directory named PRIME for a another 
directory named LEVELA, which in turn, is searched for the mytest file to 
be accessed. Note that the file or directory to be read from or written 
to is always the last element in the specified path. 
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All of the following are valid pathnames: 

a (located on system's default directory) 

able (located on system's default directory) 

:fl : /able/samp (Pathname for samp located In able directory 

on the device with prefix :F1;) 

Each time you access a file or directory for a read or write, you must 
enter the complete pathname. Once you create a new file or directory, 
its pathname remains fixed unless you choose to rename or move that file 
or directory to some new path. Note that pathname entries can be typed 
in either uppercase or lowercase letters. 


DIRECTORIES 

A directory is a specialized file used to store a list of file names and 
(optionally) other directory names in logical groupings. What 
distinguishes a directory from other files is that a directory maintains 
a formatted list of all subordinate directories and files that are 
created and assigned under its name. This formatted list of file and 
directory pathnames can be either displayed on the operator's console 
screen or written to a specified output file via the DIR command. 

A directory name is always a preceding component in the pathnames of 
files or other directories listed under that directory. You can display 
any directory's list of files and other directories by specifying the 
directory's pathname in a DIR command (see Chapter 3). 

There are two different types of directories: those supplied with the 
Human Interface, and those you create yourself by using the CREATEDIR 
command. 


SUPPLIED DIRECTORIES 

Intel supplies four directories with the Human Interface software. These 
directories each have a logical name enclosed by colon characters. When 
you wish to specifically list one of the directories, this logical name 
must be specified in the DIR command. The logical names and purpose of 
the supplied directories are as follows: 

:PROG: The user's program directory in which all user-created 

commands can be placed. When you type any command on 
the console keyboard, this is the first directory that 
the Human Interface automatically searches for that 
command. 

: SYSTEM: The directory in which the Intel-supplied Human 

Interface commands are placed. When a command is 
typed on the console keyboard, the Human Interface 
searches this directory for that command after it has 
searched the :PROG: directory. 
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:$: The prefix for the default directory on the system. 

If you do not specifically list some other directory 
in the pathname of files and directories you create 
and subsequently access during console sessions, they 
will be assigned to and listed from the default 
directory. The :$: prefix need not be specified in a 
command. 

:WORK: The user's work directory, which is a temporary or 

"scratch" work area. This directory can be used 
either programmatically by an executing command or by 
a user during a console session. Files in this 
directory are highly volatile once detached. • 

All the supplied directory assignments described previously are 
configurable options during system configuration time, including the 
order of search for command names in the :PROG: and : SYSTEM; 
directories. 


USER DIRECTORIES 

User directories are those you create during console sessions to expedite 
the management of your files. Once you create a new directory by using 
the CREATEDIR command (see Chapter 3), that directory's pathname becomes 
the preceding element in the pathname hierarchy for any file you 
subsequently assign to the directory's maintained list of files. 

For exanqptle, if a directory named LEVELA contains a directory named 
LEVELS and a data file named "test", the pathnames for LEVELS and test 
would be LEVELA/LEVELS and LEVELA/test respectively. Similarly, if the 
LEVELS directory contains a file named SAMP, the heirarchical structure 
for this tree would be as follows: 

LEVELA 

directory 

k 

LEVELS 
directory 

SAMP 

data file 

and all accesses to SAMP would require the following pathname: 
levela/ le velb ! s an^) 

Note that in the above example, the directory and file pathnames were 
assigned to the system's default user directory. All directories you 
create will automatically be assigned and listed in your system's default 
directory unless you specify the prefix for some other directory as the 
preceding element in the pathname of the new directory. 


TEST 
data file 
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VOLUMES 

A volume is a secondary storage device, such as a diskette, hard disk 
platter, or a bubble memory that you have formatted to accept files and 
directories. Before you can enter any file or directory on a new volume, 
that volume must be formatted by using the Human Interface FORMAT command 
(see the FORMAT command description in Chapter 2). 

To access a volume mounted on a device other than the default device for 
your configuration, you specify the device’s prefix as the first element 
in the pathname of the file or directory that is being created or 
accessed on the volume in that device. The prefix is actually the 
logical name for the device on which the volume is mounted; for example, 
i Fl : . See the FORMAT command in Chapter 3 and the volume access examples 
in Chapter 4 for more detailed information. 


LOGICAL NAMES 


Logical names let you refer to connections s)nDabollcally . You 
differentiate a logical name from a component of a pathname by bracketing 
the logical name with colons. You can use a logical name either as a 
prefix or in place of a pathname. 

The standard logical names and their meaning are described in Table 2-1. 
However, note that these logical name assignments are all configurable 
during system configuration time. See the iRMX 86 CONFIGURATION GUIDE 
for more information. 

You can also assign logical names to new physical devices that are added 
to the system without having to go through a system reconfiguration. See 
the ATTACHDEVICE command in Chapter 3 for more information. 


Table 2-1. Standard Logical Names 


Name 

Meaning 

;CI: 

Prefix for user console input (default input file) 

:C0: 

Prefix for user console output (default output file) 

:PR0G: 

Prefix to User Program Directory 

: SYSTEM: 

Prefix to System Command Directory) 

:$: 

Default prefix 

:W0RK: 

Prefix to User Work Directory 

:BB: 

Byte bucket 
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The full meaning of the logical names listed in Table 2-1 is as follows: 


:CI: and :C0: Logical devices that establish the source of commands 

and data and the command destination output, 
respective ly . 


:PROG: 


: SYSTEM: 




:WORK: 


BB: 


The directory where the user-designed commands are 
located. The directory name represented by :PROG: is 
a configuration option. 

The directory where the Human Interface commands are 
located. The directory name represented by : SYSTEM: 
is a configuration option. 

The user’s default directory, which is used for files 
that do not have a logical name. This directory is a 
configuration option. 

The directory to be used for temporary files and work 
("scratch") files. The directory name represented by 
:WORK: is a configuration option. 

The logical name of a device that is treated as an 
infinite sink. Anything written to :BB: will 
disappear, and a read from :BB: will receive an EOF 
(end-of-f ile) . 


SUMMARY 


During a Human Interface console session, a operator accesses system 
services interactively rather than programmatically. At this level, the 
dialog from operator to system is through keyboard commands, parameter 
options, and responses to queries or prompts. The dialog from system to 
operator is through displayed pron^ts, queries, status and error 
messages, and listed output. 

At the programming level, the Human Interface provides routines that 
allow programmers to create new commands whose syntax and structure is 
consistent with the features and requirements of the current and future 
releases of the Human Interface. 


1-8 
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This chapter describes the general syntax rules and procedures to be 
followed when using Human Interface commands at an operator's console. 
Additional and more specific information is provided in the individual 
command descriptions in Chapter 3. 

When you enter a command at the console keyboard, the associated program 
file is loaded and executed in conformance with any parameters you 
included in the command. During execution, the program may prompt or 
query you for more information as to the precise operation you wish 
performed. Following execution, the Human Interface displays status 
messages that tell you the nature and scope of the operations performed 
and whether or not execution was successful. 

Error messages may also be displayed if you attempt an invalid operation 
(e.g. , a command syntax error) or if some error is encountered while the 
command is being executed. Human Interface error messages are defined in 
the individual command descriptions in chapter 3, 

The general syntax rules described in this chapter apply equally to both 
the supplied Human Interace commands and any user-created commands that 
may have been added to your system. 


CONSOLE SESSION 

A console session begins when you enter a command at the the console 
keyboard to load and execute a program. When your iRMX 86 Operating 
System is initialized, the Human Interface displays the following message 
to let you know that it has initialized and is ready to accept your first 
keyboard command entry: 

iRMX 86 HI Vx.x: user = WORLD 


where: 


Vx.x 


Is the number of the version of the Human Interface 
that is currently running on your system. 


user = WORLD Means you have read and write access to all files and 
directories on the system. 

- (hyphen) Prompts you to enter a command. After command 

execution is completed or is prematurely terminated 
for any reason, the Human Interface displays another 
hyphen to prompt for your next command. 
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Enter your command on the same line and immediately following the hyphen 
prompt. For example: 

-copy a to b 

where everything following the hyphen is your command entry. Type a 
carriage return to end a command line and to position the cursor on a new 
line. In all examples in this manual, it is assumed that you will 
terminate every command line or data line by pressing the RETURN, LINE 
FEED, or ESC key. 


COMMAND LINE 

The elements that form a standard command entry Include a command name, 
required input parameters (if any), and optional parameters. The general 
structure of a command line that executes a file handling routine is as 
follows; 

command name inpath-list [preposition outpath-list ] [parameters] 
where: 

command name Pathname of the non-resident program file to be 

executed. After the command line is entered, the 
named program file is loaded into main memory from 
secondary storage for execution. 

inpath-list One or more pathnames for the files to be read as 

input during command execution. Multiple pathnames in 
an input file list must be separated by commas. 
Embedded blanks between pathnames are optional. See 
the description of pathlists later in this chapter. 

preposition A word that tells the executing command how you want 
the output handled. The four prepositions used in 
Intel-supplied commands are TO, OVER, AFTER, and AS. 
Your system may also have other prepositions for 
user-created commands. See the descriptions of 
prepositions later in this chapter. 

outpath-list One or more pathnames for the files that are to 

receive the output during command execution. Multiple 
pathnames specified in an output file list must be 
separated by commas. Embedded blanks between 
pathnames are optional. 

parameters Specifically requested or defaulted optional 

parameters that perform additional or extended 
services during command execution. The QUERY 
parameter that is available in some Human Interface 
commands, or the EXTENDED parameter in the DIR command 
are examples of such parameters. See the individual 
parameter descriptions for the commands in Chapter 3. 
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ADDITIONAL COMMAND SYNTAX 

line Not shown In the command line format, but terminates 

terminator the command entry on the current line and causes the 

cursor to go to a new line. The RETURN key, NEW LINE 
key, or ESC key are used as line terminators, 
depending on your hardware configuration. 

Other optional command line entries are as follows: 

An ampersand character (&) to Indicate the command 
line is continued on the next line. When you press 
the RETURN key after you press the ampersand key, the 
Human Interface displays two asterisks (**) on the 
next line to prompt for the continuation line. 

Within available memory limits, you can use as many 
continuation lines for a given command as you desire. 
After you press the RETURN key without a preceding 
ampersand character, the invoked command will receive 
the entire command string as a single command. 

Note that an ampersand within a quoted string will not 
be interpreted as a continuation mark. 

A semicolon (;) character to indicate that all text 
following it on the current line is to be read as a 
non-executable comment. Comments can also be entered 
after a continuation mark (&) is entered on a line but 
before the RETURN key is pressed. A common use of 
comments in commands is in a SUBMIT file list of 
commands (see the SUBMIT command in Chapter 3). 

Note that a semicolon within a quoted string will not 
be interpreted as a comment character. 

A command line and each succeeding continuation line for a complete 
command can have a maximum of 255 characters per line, including any 
punctuation, embedded blanks, continuation mark, non-executable comments, 
and carriage return. 

The Command Line Interpreter prescans the current line for a continuation 
mark each time you press the RETURN key. If a continuation mark is 
present, the cursor is positioned to a new line and the continuation 
pronqjt (**) is issued. If a continuation mark is not present in the line 
when the RETURN key is pressed, the command is loaded and executed. 


COMMAND LINE SYNTAX EXAMPLE: 

The following example incorporates of all of the command elements 
described in the previous general syntax subsection except a comments 
entry: 


comment 

character 


continuation 

mark 
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-copy test/sampl/data, test/more/prog to & 
**new/filel,new/f lle2 query 

where: 


Human Interface prompt for a new command entry. 


copy Name of the command to be executed, 

test/sampl/data First pathname in the input pathlist. 


, Pathname separator between input pathnames (embedded 

blank is optional). 

test/more/prog Second (and last) pathname in the input list. 

to Preposition that tells the command to copy the input 

files TO new files. 


& Continuation character that tells the Human 

Interface you wish to continue the command on the 
next line. 


RETURN Terminates the command entry on this line and 

(not shown) causes the cursor to go to a new line. 


Human Interface pronq>t to continue the command entry 
on the new line. 


new/f ilel 


y 


new/f ile2 


query 


RETURN 
(not shown) 


Pathname of the first file in the output list to 
receive the output from the corresponding file in 
the input list. 

Separator between pathnames. 

Pathname of the next file in the output list to 
receive the output from the second input file. 

Optional parameter that causes the command to pronpt 
for permission to copy each input file to each 
listed output file in the listed sequence. 

Ends the command entry and causes the command to 
be loaded from secondary storage for execution. The 
screen cursor is positioned on a new line. 


KEYBOARD CHARACTER ENTRIES 

You can type all elements of a command line in uppercase characters, 
lowercase characters, or a mix of both. The Human Interface makes no 
distinction between cases when it reads command line items, and your 
entries will appear on the screen exactly as you enter them. For 
example, you could create a new file with the pathname ’TiY/TEST" and then 
specify the file as "my/test" in subsequent file accesses. 
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INPUT AND OUTPUT PARAMETERS 


An input parameter consists of a pathname or pathname-list of files on 
which a command is to operate. An output parameter defines the 
destination or destinations of the processed output. Input and output 
parameters may consist of the pathnames for one or more files or 
directories, or logical names, where a logical name is a shorthand way 
(prefix) of referring either to some physical device configured into your 
system or to a file. The prefix is always enclosed by colons; for 
Instance, :F1; or :PROG:. 

An input parameter is required for all file handling commands. An output 
parameter is also generally required but the default TO :C0: (to console 
screen) can be used in most commands. See the individual command 
descriptions in Chapter 3 for a a description of default parameters. 


PATHLISTS 

A pathllst is a list of pathnames, separated by commas, that comprises an 
input or output parameter. A command reads the pathnames in a pathlist 
in the sequence in which you enter them. Such lists of pathnames are 
referred to in this manual as "inpath-lists" and "outpath-lists" 
respectively. The example: 

. . . PRIME /urfile,LEVEL3/samp, LEVEL5/TEST/one. . . 

is a valid pathlist consisting of three pathnames, two of which are 
separated by a comma, and the last separated by both a comma and a 
separating blank. 

The Human Interface also recognizes your console keyboard and console 
screen as an "input file" and an "output file" respectively, and are 
specified in a command line as follows: 

:CI: The logical name prefix for the console input device 

(console keyboard). Specifying :CI: in a command line 
tells the command to read input from the console 
keyboard. 

:C0: The logical name prefix for the console output device 

(console screen). For some commands such as COPY, TO 
:C0: is the default output file if a preposition and 
output file are not specified. For example, the 
command: 

copy test 

causes the COPY command to write the contents of file 
TEST TO the console screen by default. 
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PREPOSITION PARAMETERS 


Preposition parameters in a command line tell the the command how you 
want it to process the output file or files. The Human Interface file 
management commands usually provide three options in the choice of a 
preposition: TO, OVER, and AFTER, with AS as yet another preposition used 
in the ATTACHDEVICE command. The TO preposition and ;C0: (console 
screen) will be used by default if you do not specify a preposition and 
an output file. The prepositions have the following meaning: 

TO Causes the command to send the processed output to new files; 

that is, to files that do not already exist in the given 
directory. If a listed output file does already exist, the 
command will display the following query on the console 
screen: 

pathname, already exists, DELETE? 

Enter a Y or y if you wish to delete the existing file. 

Enter any other character if you do not wish the file to be 
deleted. If a Y is not entered, the executing command will 
not process the corresponding input file but will go to the 
next input filein the command line. The listed input files 
are processed and written to the output files on a 
one-for-one basis in the listed sequence. For example: 

-copy a,b to c,d 

where file a is copied to file c, and file b is copied to 
file d. 


OVER Causes the command to write your input files over the output 
files in the listed sequence, irrespective of whether or not 
the output files already exist. For example: 

-COPY sampl,samp2 OVER outl,out2 

copies the data from file SAMPl over the present contents of 
file OUTl, and copies the data of SAMP2 over the contents of 
file 0UT2. 

AFTER Causes the command to append the contents of one or more 

files to the end of one or more new or existing files (file 
concatenation). For example: 

-copy lnl,in2 after destl,dest2 

causcis the contents of file INI to be written to the end of 
the contents of DESTl, and the contents of INI to be added to 
the end of DEST2. 
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AS Causes a physical device specified in an ATTACHDEVICE command 

to be cataloged in the system's logical-name directory AS the 
logical name specified in the command. All subsequent 
accesses to the device, either interactively by keyboard 
command or programmatically, must be performed by specifying 
the cataloged logical name unless that logical name is 
configured into the system as the standard default prefix. 


CONTROL KEYS 

CONTROL keys allow you to enter control commands to the Terminal 
Handler. You invoke control commands by pressing the CTRL key, and while 
holding it down, also pressing the required alphabetical key. In this 
manual, CONTROL key functions are designated as follows: 

CTRL/ character 

where CTRL specifies the CONTROL key, and character is the alphabetic 
character used to perform the desired action. The CTRL keys and their 
actions are as follows: 

CTRL/z Signals end-of-file for keyboard entry applications. 

CTRL/z should be entered on a new line because a 
RETURN or LINE FEED will not be appended to the end of 
the last data line. 

CTRL/c Tells the Human Interface to abort the currently 

executing program. 

CTRL/d Invokes the iRMX 86 Debugger (if configured in your 

system). 

CTRL/o Suppresses output if output is in nornal mode, or 

restores output to normal mode if output is already 
suppressed. 

CTRL/s Suspends writing to the output file. 

CTRL/q Resumes writing to the output file. 

CTRL/x Deletes the current displayed line during keyboard 

input. 

CTRL/r Operates in two modes: if the current line is empty, 

CTRL/r sends the previous line to the console output 
device so that you can edit and submit the line as a 
new command; if the current line is not empty CTRL/r 
sends a RETURN to the console output device, followed 
by a reentry of the current line. 
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Other key operations that can be used are as follows: 


RUBOUT Permits simple line editing on the current line. The 

handling depends upon how the Terminal Handler option 
was configured in your system. In one option, each 
time the RUBOUT key is pressed, the last displayed 
character is deleted with the cursor moving backward 
one space across the line. You continue pressing the 
RUBOUT key until you reach the character to be 
corrected. In the other option, the deleted character 
is echoed back to the console output device. 


RETURN, ESC, Signals the end of a command line or line of data and 

or positions the cursor on a new line. In this manual, 

LINE FEED use of the RETURN key is assumed in command exat]q)les. 


FILE HANDLING CONSIDERATIONS 


Several of the Human Interface commands require that you specify a 
preposition parameter in the command line. That is, you must enter a TO, 
OVER, or AFTER preposition as one of the command line parameters. In 
such cases, the number of Input files you list, as opposed to the number 
of output files, can directly affect the way in which the command handles 
the preposition and the way the files are processed. 

Usually (but not necessarily), you will be specifying a one-for-one match 
between the number of input files and output files. There are situations 
where you can combine preposition functions. 

For exan5)le, in a command (other than RENAME), if you specify more 
pathnames in the input list than in the ouput list, the remaining input 
files will be automatically appended to the end of the last specified 
output file, regardless of what preposition you specified. 

This flexibility in file handling allows you to combine one-for-one file 
operations (as in TO or OVER preposition) with file concatenation (as in 
the AFTER preposition) in a single command, and thus avoid entering an 
extra command to perform a separate concatenation operation. For 
Instance, assume that in a COPY command, you use the TO preposition and 
specify the following file names in the input and output parameters: 

copy a,b,c TO d,e 

When you execute the command line, file "a" will be copied to file "d", 
and files "b" and "c" will be appended to the end of file "e" as follows: 

a TO d 
b TO e 
c AFTER e 
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Conversely, If you specify fewer file names in the input list than in the 
output list of a command line, the excess output file names will be 
ignored, regardless of which preposition you specify. For example, 
assume that in a command line you specify the following file names in the 
input and output parameters: 

copy a,b TO d,e,f,g 

When the command is executed, file "a" will be matched with file "d", 
file "b" matched with file "e", and files "f" and "g” will be ignored, as 
follows: 

a TO d 
b TO e 

Preposition parameters cannot be combined in a RENAME command; that is, 

TO or OVER prepositions do not convert to an AFTER preposition if there 
are more input files than output files. 


DIRECTORY LISTINGS 

A directory listing contains a list of files and other directories that 
you assign to it. You can list a directory on the console screen or to a 
named output file by using the DIR command and specifying the directory's 
pathname (if you omit a directory name in a DIR command, the default user 
directory will be listed). The amount of information provided for each 
listed file or directory, and the format of the directory listing depend 
on which parameter option you specify in the DIR command. See the DIR 
command description in Chapter 3. 


FILE HANDLING SAFEGUARDS 

A mismatch between the number of input file and output files is more apt 
to be accidental than something you perform Intentionally. The key point 
is that Human Interface commands always attempt to perform as many of 
your command line specifications as possible, without destroying l;he 
integrity of your files. As the operation for each listed file is 
successfully executed, the command displays a message that identifies the 
file and defines precisely what operation was performed. 

When a command encounters a parameter item that is subject to ambiguous 
interpretation or could result in the accidental destruction of an 
existing file, the command usually displays a query message and prompts 
you to confirm or cancel the specific operation for that file. See the 
command descriptions in Chapter 3 for a definition of the messages. 
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CHAPTER 3. HUMAN INTERFACE COMMANDS 


The commands described in this chapter are supplied by Intel for IRMX 86 
Operating Systems that are configured with the Human Interface. You can 
use the commands to perform a number of highly convenient file management 
functions or to invoke various utility routines. 

If you are a new user of the Human Interface, it is suggested that you 
review the command syntax and invocation considerations in Chapter 2 
before reading the command descriptions provided in this chapter. 

The commands described in this chapter assume that your iRMX 86 system is 
configured with the Human Interface commands resident in secondary 
storage under the : SYSTEM: directory), and any user-created commands 
resident in the ;PROG; directory. When you enter any command 
(Intel-supplied or user-created) using this configuration, the Human 
Interface always searches for the command in the :PROG: directory first 
and the : SYSTEM: directory second. 

The commands are presented in alphabetical sequence without regard for 
functional organization. A functional grouping of the commands is given 
in the Human Interface Command Dictionary in Table 3-1 for fast reference. 


COMMAND SYNTAX SCHEMATICS 


The syntax for each command described in this chapter is presented by 
means of a "railroad track" schematic, with syntactic elements scattered 
along the track. Your entrance to any given schematic is always from 
left to right, beginning with some command name entry. 

Elements shown in uppercase characters must be typed in a command line 
exactly as shown in the command schematics except that you can type them 
either in uppercase or lowercase characters; the Human Interface makes no 
distinction between cases in alphabetic characters. Syntactic elements 
shown in lowercase characters are generic terms, which means that you 
supply the specific item, such as the pathname for a file. 

The example that follows shows all the possible paths through a railroad 
track schematic. Notice that the main track goes through required 
elements in a given command. 

"Railroad sidings" go through optional parameter elements. In some 
cases, you have a choice of going through one of several possible sidings 
before returning to the main track. In still other cases, the main track 
Itself diverges into two separate tracks, which means that you must 
select one parameter or the other but not both. 
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(START) 



In this example: 

• A is a required element. 

• Either B or C is required but not both. 

• D, E, or F are all optional but only one can be selected. 

• G is required. 
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Table 3-1. Human Interface Command Dictionary 


Command 

Synopsis 

Page 


File and Volume Management Commands 


ATTACHDEVICE 

Attaches a new physical device to the system 
and adds its logical name to the root job’s 
object directory. 

3-5 

BACKUP 

Copies named files to a backup volume. 

3-8 

COPY 

Creates new data files, or copies files to other 
pathnames . 

3-15 

CREATEDIR 

Creates one or more new directories. 

3-18 

DELETE 

Deletes data files and empty directories from a 
volume on secondary storage. 

3-22 

DETACHDEVICE 

Removes a physical device from system use and 
deletes its logical name from the root job's 
object directory. 

3-24 

DIR 

Lists a directory’s filenames (and optionally, 
file attributes). 

3-25 

DISKVERIFY 

Verifies the data structures of named and 
physical volumes. 

3-32 

DOWNCOPY 

Copies files and directories from an iRMX 86 
volume mounted on a secondary storage device to 
an ISIS-II secondary storage device. 

3-37 

FORMAT 

Formats an iRMX 86 volume. 

3-40 

RENAME 

Renames files or directories. 

3-45 

RESTORE 

Copies files from a backup volume to a named 
volume. 

3-48 

UPCOPY 

Copies files and directories from an ISIS-II 
secondary storage device to an iRMX 86 volume 
mounted on a secondary storage device. 

3-59 
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Table 3-1. Huipan Interface Command Dictionary (continued) 


Command 

Synopsis 

Page 


General Utility Commands 


DATE 

Sets or resets the system date, or displays the 
current date. 

3-20 

DEBUG 

Transfers control to the iSBC 957A/B package to 
debug an iRMX 86 application program. 

3-21 

SUBMIT 

Reads, loads, and executes a string of commands 
from secondary storage instead of the keyboard. 

3-55 

TIME 

Sets or resets the system clock, or displays the 
current system time. 

3-58 


3 








ATTACHDEVICE 


ATTACHDEVICE 


This command attaches a physical device to the iRMX 86 Operating System 
and catalogs the device’s specified logical name in the root job’s object 
directory. 

The format of the command is as follows: 



INPUT PARAMETERS 


physical device Physical device name of the device to be attached 

to the system. This name should be the name of 
one of the Basic I/O System’s Device Unit 
Information Blocks (DUIB), as defined at system 
configuration time. 

AS : logical name: Preposition plus logical name that causes the 

physical device to be cataloged in the object 
directory AS the specified logical name. After 
the device is attached and cataloged via the 
ATTACHDEVICE command, any command or program code 
that accesses the device must specify the logical 
name unless the device uses the default prefix as 
its logical name. 

NAMED Specifies that the volume mounted on the device is 

already formatted for NAMED files. Examples of 
named-file volumes are diskettes or hard disk 
platters. If neither NAMED nor PHYSICAL are 
specified, NAMED is the default. See the FORMAT 
command in this chapter for a further description 
of NAMED files. 


PHYSICAL Specifies that the volume mounted on the logical 

device is already formatted as a single, large 
file. An exanq>le is a line printer. See the 
FORMAT command in this chapter for a further 
description of PHYSICAL volumes. 
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DESCRIPTION 

A physical device must be attached to the system and cataloged in the 
root job's object directory before it can be accessed via the logical 
name you assigned at the time the device was attached. Physical devices 
must have been declared in the Basic I/O System's Device Unit Information 
Block (DUIB) at configuration time before they can be attached with the 
ATTACHDEVICE command. 

The most frequent use of the ATTACHDEVICE command is to attach a new 
device, such as a new disk drive or a line printer, without having to 
reconfigure the system. (See the DETACHDEVICE command in this chapter 
for a description of how to detach a device from the system without 
reconfiguring. ) 

When the attachment is completed, the ATTACHDEVICE command displays the 
following message: 

physical name, attached as logical name 

where "physical name" and "logical name" will be as specified in the 
ATTACHDEVICE command. 


ERROR MESSAGES 

logical name, device already attached 

The specified device is attached but is not cataloged. ATTACHDEVICE does 
not attach the device. 


device name, device does not exist 

The physical device name you specified does not correspond to a name the 
Basic I/O System recognizes. That is, there is no DUIB defined for the 
device you specified. ATTACHDEVICE does not attach the device. 


logical name, invalid logical name 

The logical name specification is not enclosed with colons, contains 
unmatched colons, is longer than 12 characters, or contains invalid 
characters. ATTACHDEVICE does not attach the device. 


logical name, logical name already exists 

The specified logical name is already cataloged in the root job's object 
directory. ATTACHDEVICE does not attach the device. 
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physical device, may not be attached as a (NAMED or PHYSICAL) 

The NAMED or PHYSICAL specification in the command is not allowed for 
that physical device; for example, defining a line printer as a NAMED 
volume. ATTACHDEVICE does not attach the device. 


00 8A : E$C0NTR0L, too many device names 

You tried to attach more than one physical device with a single 
ATTACHDEVICE command. ATTACHDEVICE does not attach a device. 


logical name, volume is not a named volume 

ATTACHDEVICE attempted to attach a device as a named device and 
discovered a physical volume on the device. However, ATTACHDEVICE does 
attach the device. 


logical name, volume not formatted 

ATTACHDEVICE attempted to attach a device as a named device and 
encountered an I/O error while searching for the volume's root 
directory. However, ATTACHDEVICE does attach the device. 


logical name, volume not mounted 

'Che specified device does not contain a volume. However, ATTACHDEVICE 
does attach the device. 


logical name, exception code 

ATTACHDEVICE was unable to attach the specified device. This message 
lists the IRMX 86 exception code encountered. 
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BACKUP 


This command saves files in a named volume by copying them to a physical 
volume which serves as a backup volume. Later, you can use the RESTORE 
command (described later in this chapter) to retrieve these files and 
copy them to named volumes. 

The format of this command is as follows: 



INPUT PARAMETERS 

pathname Pathname of a file on the source volume. BACKUP 

saves files from the branch of the file tree that 
begins with the specified file. If you specify 
the logical name of the device only, BACKUP saves 
files beginning with the root directory of the 
VO lume . 

*dd mmm yy’ Date parameter that BACKUP uses, in conjunction 

with the time parameter, to determine which files 
to save. BACKUP saves only those files that have 
been modified since the specified date and time. 
You must enclose the date parameter in single 
quotes. The individual fields of this parameter 
are: 

dd Two-digit number that specifies the day of 
the month. 

mmm Three-character abbreviation for the 
month, as follows: 


JAN 

APR 

JUL 

OCT 

FEB 

MAY 

AUG 

NOV 

MAR 

JUN 

SEP 

DEC 


yy Two-digit number that specifies the year. 

If you omit this parameter but specify the time 
parameter, the date defaults to the current 
system date. If you omit both the date and time 
parameters, the date defaults to 1 JAN 78. 
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INPUT PARAMETERS (continued) 

hh:mm;ss Time parameter that BACKUP uses, in conjunction 

with the date parameter, to determine which files 
to save. BACKUP saves only those files that have 
been modified since the specified date and time. 
The individual fields of this parameter are: 

hh Hours specified as 0-24. 

mm Minutes specified as 0-59. 

ss Seconds specified as 0-59. 

If you omit this parameter, the time defaults to 

00 : 00 : 00 . 

QUERY Causes the Human Interface to prompt for 

permission to save each file. The Human Interface 
prompts with one of the following queries: 

pathname, BACKUP data file? 

or 

pathname, BACKUP directory? 

Enter one of the following responses to the query: 


Entry 

Action 

Y or y 

Save the file. 

E or e 

Exit from the BACKUP command. 

R or r 

Continue saving files without 
further query. 

Any other 
character 

If data file, do not save the 
file; if directory file, do not 
save the directory or any file in 
that portion of the directory 


tree. Query for the next file, if 
any . 


OUTPUT PARAMETER 

: backup device: Logical name of the device to which BACKUP copies 

the files. 
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DESCRIPTION 

BACKUP is a utility which saves named files on backup volumes, such as 
diskettes. BACKUP saves the following information for each file: 

• File name 

• Access list 

• Extension data 

• User ID of the file owner 

• File granularity 

• Contents of the file 

You can copy this information back to a named file by using the RESTORE 
utility, described later in this chapter. 

Before a volume can be used as a backup volume, the volume must be 
formatted. Although BACKUP will accept both physical and named volumes, 
it is recommended that you supply freshly-formatted physical volumes or 
old backup volumes for this purpose. BACKUP issues a message before 
continuing if the backup volume you supply is anything other than a 
freshly-formatted physical volume. When BACKUP copies files to the 
backup volume, it overwrites any information that currently exists on the 
volume. 

In order for BACKUP save files from a named volume, you must have read 
access to the files and to the directories that contain them. 

You can limit the files which BACKUP processes in the following ways: 

• If you specify a complete directory name Instead of just the 
device's logical name in the invocation line, BACKUP limits its 
processing to the specified directory and all subdirectories. 

• If you specify the date and time parameters, BACKUP processes 
only those files modified since the specified time. 

• If you specify the QUERY parameter, BACKUP asks permission before 
saving each file. If you deny permission for BACKUP to save a 
data file, BACKUP skips the file and continues with the next 
file. If you deny permission for BACKUP to save a directory 
file, BACKUP skips the directory and all files contained in the 
directory or its subdirectories. 

When you enter the BACKUP command, BACKUP displays the following sign-on 
message: 

iRMX 86 DISK BACKUP UTILITY, Vx.x 

where Vx.x is the version number of the utility. It then prompts you for 
a backup volume. 
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DESCRIPTION (continued) 


Whenever BACKUP requires a new backup volume, it displays the following 
message: 

backup device, mount backup volume #nn, enter Y to continue: 

where backup device indicates the logical name of the backup device and 
nn the number of the requested volume. (BACKUP in some cases displays 
additional information to indicate problems with the current volume.) In 
response to this message, place a volume in the backup device and enter 
one of the following: 


Entry 

Y, y, R or r 

E or e 

Any other 
character 


Action 

Continue the backup process. 

Exit from the BACKUP command. 
Invalid entry; reprompt for entry. 


BACKUP continues prompting for a backup volume until you supply one that 
it can access. 

If the backup volume you supply is not a freshly-formatted physical 
volume, but one that BACKUP can access (such as a named volume, a 
previously-used backup volume, or a physical volume containing data), 
BACKUP Informs you of this with one of the following messages: 

backup device, not a physical volume, enter Y to overwrite: 


or 


backup device, backup volume #nn, date, enter Y to overwrite: 

where backup device is the logical name of the backup device, nn is the 
volume number of the backup volume, and date is the date on which the 
previous backup was performed. In response to these messages, enter one 
of the following: 

Entry 

Y, y, R, or r 

E or e 

Any other 
character 


Action 

Use the volume as a backup volume, overwriting the 
Information currently stored on the volume. 

Exit from the BACKUP command. 

Reprompt for another volume. 
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DESCRIPTION (continued) 

As BACKUP saves each file in the source volume, it displays the following 
message at the Human Interface console output device (:C0:): 

pathname, SAVED 

If your backup volume becomes full and you supply additional backup 
volumes, you should write the numbers of the backup volumes on the volume 
labels. Later, when you later restore files to a named volume with the 
RESTORE utility, you must supply the backup volumes in order. 


ERROR MESSAGES 

backup device, backup volume #nn, date, enter Y to overwrite: 

The backup volume you supplied already contains backup information. 

BACKUP lists the logical name of the backup device, the volume number, and 
the date on which the original backup occurred. It overwrites this volume 
if you enter Y, y, R, or r. 


backup device, cannot attach volume 
backup device, exception code 

backup device, mount backup volume //nn, enter Y to continue: 

BACKUP cannot access the backup volume. This could be because there is no 
volume in the backup device, the volume is write protected, or because of 
a hardware problem with the device. The second line of the message 
indicates the iRMX 86 exception code encountered. BACKUP continues to 
issue this message until you supply a volume that BACKUP can access. 


pathname, exception code, cannot back up file 

For some reason BACKUP could not copy a file from the named volume, 
possibly because you do not have read access to the file or because there 
is a faulty area on the named volume. The message lists the pathname of 
the file and the exception code encountered. BACKUP copies as much of the 
file as possible and continues with the next file. 


backup device, error writing volume label 
backup device, exception code 

backup device, mount backup volume #nn, enter Y to continue: 

When BACKUP attempted to write a label on the backup volume, it 
encountered an error condition, possibly because of a faulty area on the 
volume, or because the volume is not formatted. The second line of the 
message indicates the iRMX 86 exception code encountered. BACKUP 
reprompts for a different backup volume. 
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ERROR MESSAGES (continued) 

pathname, file does not exist 

The pathname you specified as input to BACKUP does not represent an 
existing file or device. 

backup device, invalid backup device 

The logical name you specified for the backup device was not a logical 
name for a device. 


exception code, invalid DATE or TIME 

For either the DATE or TIME parameter, you entered a value that is out of 
range (such as 31 FEB 81 or 26:03:62). The message lists the exception 
code encountered as a result of this entry. 

backup device, invalid logical name 

The logical name you specified for the backup device contains unmatched 
colons, is longer than 12 characters, contains invalid characters, or 
does not exist. 

backup device, not a physical volume, enter Y to overwrite: 

The backup volume you supplied was formatted as a named volume or 
contained some other information. BACKUP will overwrite this volume if 
you enter Y, y, R, or r. 


output specification missing 

You did not supply the logical name of the backup device when you entered 
the BACKUP command. 


keyword, too many values 

You entered too many values with either the DATE or TIME parameters . The 
keyword portion of the message indicates the parameter that is in error. 


keyword, unrecognized control 

You entered one of the optional parameters of the form "keyword=value, 
but the keyword was not DATE, TIME, or QUERY. 
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ERROR MESSAGES (continued) 

backup device, volume not formatted 

backup device, mount backup volume //nn, enter Y to continue: 

The backup volume you supplied was not formatted. BACKUP continues to 
issue this message until you supply a formatted backup volume. 

backup device, write error on backup volume 
backup device, exception code 

BACKUP encountered an error condition when writing information to the 
backup volume. The second line of the message lists the exception code 
encountered. This error is probably the result of a faulty area on the 
volume. 


pathname, exception code 

The pathname you specified as input to BACKUP is in error. This error 
could occur if you specify the same logical name that you specified for 
the backup device. It could also occur if you specify an invalid or 
nonexistent path component. This message displays the exception code 
that results from this error. 
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COPY 

This command reads data from the specified input source or sources and 
writes the output to the specified destination file or files. 

The format of the command is as follows; 



INPUT PARAMETERS 
inpath-list 


QUERY 


One or more pathnames for the files to be copied. 
Multiple pathnames must be separated by commas. 
Separating blanks are optional. To copy files on 
a one-for-one basis, you must specify the same 
number of files in the inpath-list as in the 
outpath-list. 


Causes the Human Interface to prompt for 
permission to copy each file. Depending upon the 
specified preposition (TO, OVER, or AFTER), the 
Human Interface prompts with one of the following 
queries: 


pathname, copy TO out-pathname? 
pathname, copy OVER out-pathname? 


pathname, copy AFTER out-pathname? 

Enter one of the following (followed by a carriage 
return) in response to the query: 


Entry 
Y or y 
E or e 
R or r 

Any other 
character 


Action 

Copy the file. 

Exit from COPY command 
Continue copying files without 
further query. 

Do not copy this file; go to the 
next file in the input list. 
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OUTPUT PARAMETERS 

Writes the listed input files to named new 
output files. The specified output file or 
files should not already exist; if they do, COPY 
will request permission to delete the existing 
files before it executes the copy operation for 
that file. If more input files than output 
files are listed, the remaining input files will 
be appended to the end of the last listed output 
file. 

Writes the listed input files over (replaces) 
the existing output files on a one-for-t>ne 
basis, regardless of file size. If an output 
file does not already exist, its corresponding 
input file is written to a new file with the 
listed output file name. If more input files 
than output files are listed, the remaining 
input files will be appended to the end of the 
last listed output file. 

Appends the input file or files to the current 
data in the existing output file or files. If 
the output file does not already exist, all 
listed input files will be concatenated into a 
new file with the listed output file name. 

outpath-llst One or more pathnames for the output files. 

Multiple pathnames must be separated by commas. 
Separating blanks are optional. If the 
preposition and output parameter defaults are 
exercised in the command line, the output will 
gb to the user’s console screen (TO :C0;). 


DESCRIPTION 

COPY is a powerful and versatile command with a wide range of file 
handling applications (see Chapter 4 for exan^les). Implementation 
depends upon your selection of a preposition and your input file and 
output file specification in the command line. The following are some 
of the COPY command’s features: 

• Create new files (TO preposition). 

• Copy over existing files or create new files (OVER preposition). 

• Add data to the end of existing files (AFTER preposition). 

• Copy a list of files to another list of files on a one-for-one 
basis. 

• Concatenate two or more files into a single output file. 


OVER 


AFTER 
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DESCRIPTION (continued) 

As each file is copied, the COPY command displays one of the following 
messages, as appropriate: 

pathname, copied TO out-pathname 

pathname, copied OVER out-pathname 

pathname, copied AFTER out-pathname 

If you do not specify a preposition or output file, TO :C0: is the 
default output. The Human Interface normally expects all listed output 
files to be new files when the TO preposition is used; however, it is 
prepared to deal with existing files. If an existing output file name 
is encountered during a copy operation using TO, the Human Interface 
displays the the following message; 

pathname, already exists, DELETE? 

Enter Y or y if you wish to delete the existing file. The COPY command 
will delete the file. 

Enter any other character if you do not wish to delete the existing 
file. The COPY command will pass over the corresponding input file 
without copying it, and will attempt to copy the next listed input file 
to its corresponding output file. 

If more input files than output files are specified, the remainder of 
the input files will be appended to the end of the last listed ouput 
file. As each file is appended, the following message is displayed on 
the console screen: 

pathname, copied AFTER out-file 

If there are fewer input filenames than output filenames specified in 
the COPY command (regardless of the preposition), the output files 
remaining after the last valid copy operation will be ignored. 

You cannot successfully use COPY to copy a directory to a data file or 
to another directory. Although a directory can be copied, the 
attributes of the directory are lost. That is, the directory can no 
longer be used as a directory. However, a file listed under one 
directory can be copied to another directory. For example: 

copy samp/test/a to :fl: /alpha/beta 

would copy the A data file to a different volume, directory, and 
filename, where the new file’s pathname would be ; fl : /alpha/beta. 
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CREATEDIR 


This command creates one or more IRMX 86 user directories. 
The format is as follows: 



One or more pathnames of the iRMX 86 directories 
to be created. Multiple pathnames must be 
separated by commas. Embedded blanks between 
commas and pathnames are optional. 


A created iRMX 86 directory allows all access functions; that is, you can 
read /write, delete, list, add, and change the contents of the directory 
you created with CREATEDIR. 

The following message is displayed if a directory is successfully created: 
directory-name, directory created 

You can create new directories that are subordinate to other directories. 
For example: 

createdir ab/dc/ef/GH 

would cause the newly-created directory GH to be nested within existing 
directory EF, which in turn, is nested within directory DC, and so on. 

It is suggested that you use uppercase letters when you enter a new 
directory name in a CREATEDIR command, and use lowercase letters when you 
create a new data filename in a COPY command. You can then easily 
distinguish between directory names and filenames in a directory listing. 

You can check the contents of the directory at any time by using the DIR 
command to list the directory (see the DIR command in this chapter). 


INPUT PARAMETER 
inpath-list 

I 

DESCRIPTION 


ERROR MESSAGES 

directory name, invalid file type 
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ERROR MESSAGES (continued) 

You attempted to create a directory using a data file as part of the new 
directory’s pathname; only other directory names are allowed in the 
pathname for a new directory. 

directory-name, directory already exists 

The specified pathname of the directory to be created already exists. 
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DATE 


This command sets a new system date or displays the current date. 
The format is as follows: 



INPUT PARAMETERS 


dd Two-digit number that specifies the day of the month. 

mmm Three -character abbreviation for the specified 

month, as follows: 


JAN 

APR 

JUL 

OCT 

FEB 

MAY 

AUG 

NOV 

MAR 

JUN 

SEP 

DEC 


yy Two-digit number that specifies the year. 


DESCRIPTION 

The dd, mmm, and yy entries are separated by single blanks. 

If no new date is specified in the DATE command, the current date is 
displayed. 

If one of the date entries in the parameter string is set, all three must 
be; there are no default settings for individual entries within the 
parameter string. 

If you request the system date on a non-timing system, the following 
message will be displayed: 

00 : 00:00 

See also the TIME command in this chapter if you wish to set the system 
clock in conjunction with setting the date. 


ERROR MESSAGES 

Errors in a date entry, such as syntax errors or a number out of range 
(l.e., 31 FEB 81), cause the following error message to be displayed: 

illegal date 

If this occurs, reenter the DATE command with the correct syntax. 
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DEBUG 


This command allows you to debug your iRMX 86 application jobs if your 
system is configured with the iSBC 957A/B package. 



INPUT PARAMETERS 

command pathname Pathname of the file containing the application 

program to be debugged. 

parameter string String of required, optional, and default 

parameters that can be used in the command line to 
load and execute the application program. 


DESCRIPTION 

DEBUG loads your specified application program into main memory and 
transfers control to the iSBC 957A/B package. You can then use the iSBC 
957A/B package to single-step, display registers, and set breakpoints 
within the program. Refer to the appropriate iSBC 957A or iSBC 95 7B 
user’s guide for a complete description of the iSBC 957A/B functions. 

When DEBUG executes, the 957A/B package runs with its interrupts 
disabled. Therefore, the time-keeping function is also disabled, with 
the following consequences: 

• Impacts the ability of the Nucleus to execute time-out tasks that 
have provided time limits to system calls, such as RECEIVE$UNITS 
and RECEIVE$MESSAGE. 

• Impacts the ability of the Basic I/O System to keep track of the 
time-^f-day and write its data structures to secondary storage. 

The 957A/B package cannot tolerate interrupts while the single-stepping 
command is being used. Single -stepping will be affected if: 

• Tasks are using non-zero time-out values in system calls such as 
RECEIVE $UNITS and RECEIVE$MESSAGE. 

• Tlme-of-day is configufed in the Basic I/O System. 

• Non-zero update timeout values are specified in the Basic I/O 
System’s Device Unit Information Blocks (DUIB). 

'Che alternative to single-stepping is to use breakpoints. 
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DELETE 


This command removes data files and enq>ty directories from secondary 
storage. 

The format is as follows: 



INPUT PARAMETERS 

inpath-list One or more pathnames for the files or eiqpty 

directories to be deleted. Multiple pathname 
entries must be separated by commas. Separating 
blanks are optional. 

QUERY Causes the DELETE command to ask for your 

permission to delete each file in the list. Prior 
to deleting a file, the DELETE command displays 
the following query; 

pathname, DELETE? 

Enter one of the following, followed by a carraige 
return, in response to the query: 


Entry 

Action 

Y or y 

Delete the file. 

E or e 

Exit from DELETE command. 

R or r 

Continue deleting without further 
query . 

Any other 

Do not delete file; 

character 

query for next file in sequence. 


DESCRIPTION 

The DELETE command allows you to release unused secondary storage space 
for new uses by removing empty directories and unneeded data files. If a 
file to be deleted is currently attached, it will be marked for deletion 
and deleted when the file is detached. 

The following message is displayed as each file is deleted or marked for 
deletion: 

pathname, deleted 
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ERROR MESSAGES 

pathname, DELETE access required 
You do not have permission to delete a specified file, 
pathname, does not exist 

The specified file was not found (e.g., a syntax error in a pathname or 
the file is located in some other directory). The DELETE command will 
atte^^)t to delete each succeeding file specified in the filename-list 
after it has encountered an error in a file name. 

pathname, directory not enq>ty 

Non-empty directories may not be deleted. You attempted to delete a 
directory that still lists filenames or other directory names. 

If you still wish to delete the directory, you must first delete all its 
contents. For example, if you wished to delete a directory named ALPHA 
that contained a data file with the pathname ALPHA/BETA/SAMP, you would 
enter the following command: 

delete alpha/beta/sanq> , alpha/beta, alpha 

which would delete all files cataloged in ALPHA before the directory 
itself was deleted. 
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DETACHDEVICE 


This command detaches the specified logical device and deletes the entry 
from the root job’s object directory. 



INPUT PARAMETER 

; logical name: Logical name of the physical device that is to be 

deleted from the root job’s object directory. 


DESCRIPTION 

The DETACHDEVICE command allows you to detach a device without having to 
reconfigure the system. After a device is detached, no volume mounted on 
that device is accessible for system use. For a description of formatted 
volumes (NAMED or PHYSICAL), see the FORMAT command description in this 
chapter. 

When the device is detached and its logical name has been deleted from 
the root job’s object directory, the DETACHDEVICE command will display 
the following message: 

logical-name, detached 


NOTE 

Using the DETACHDEVICE command to 
detach the device containing your Human 
Interface commands causes loss of 
access to Human Interface functions 
until the system is restarted. 


ERROR MESSAGE 

illegal logical name 

Either there is a syntax error in the logical name specification or the 
logical name does not exist in the root job’s object directory. 


3-24 


DIR 


DIR 


This command lists the names and attributes of files contained in a given 
directory, including data filenames and directory names. 

The format of the command is as follows: 



INPUT PARAMETERS 
inpath-1 1st 


EXTENDED 


LONG 


One or more pathnames of the directories to be 
listed. Multiple directory pathname entries mist 
be separated by commas. Separating blanks are 
optional. If no pathname is specified, the user’s 
default directory is listed. 

Lists all available Information for each data file 
or directory file in the directory. The first 
line for each file will be the same as for the 
LONG form. The second line will contain the last 
access date, creation date, and the accessor 
list. The listing will be in a double-column 
format (see Figure 3-1 at the end of this command 
description). 

Lists file information in a one-line format (see 
Figure 3-2 at the end of this command description). 
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INPUT PARAMETERS (continued) 


FAST 

SHORT 

ONE 

QUERY 


OUTPUT PARAMETERS 
TO 

OVER 

AFTER 

out-pathname 


Lists only the filenames and directory names in 
the directory. The output format will be five 
columns of filenames unless you also specify the 
ONE parameter (see Figure 3-3 at the end of this 
command description). If no listing format is 
specified, FAST is the default. 

Lists the file information in a two-column format 
(see Figure 3-4 at the end of this command 
description). 

Lists the output of a FAST or SHORT listing in 
single -column format. ONE is the default number 
of columns for EXTENDED or LONG listings. 

Causes the DIR command to prompt you for 
permission to list a directory by issuing the 
following message: 

pathname, DIR? 

Enter one of the following (followed by a carriage 
return) in response to the query: 


Entry 

Action 


Y or y 

List the directory. 


E or e 

Exit from DIR command. 


R or r 

Continue listing directories 
further query. 

without 

Any other 

Do not list directory; query 

for the 

character 

next directory, if any. 



Copies the directory listing to the specified 
destination data file. If no TO /OVER/AFTER 
preposition is specified, TO :C0: is the default. 

Copies the directory listing to the specified 
output file and writes over (replaces) the 
previous contents. 

Appends the directory listing to the current 
contents of the specified output file. 

Pathname of the file to receive the directory 
listing. If the parameter is omitted, the default 
destination is the user’s console screen (TO :C0:). 
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DESCRIPTION 

The amount of Information listed for each file depends upon what 
listing format you specify (EXTENDED, FAST, LONG, or SHORT) in the 
DIR command. An example of each type of listing format is provided 
at the end of the DIR command description in Figures 3~1 through 3-4 
respectively. An explanation of the illustrated headings is provided 
in Table 3-2 following the figures. 

If you want to list the default user directory but also wish to 
specify a listing format other than FAST, use the default directory 
name explicitely. For example: 

dir :$: extended 

would display a listing of the user directory in the EXTENDED 
format. Note that the default directory is a configuration option. 


ERROR MESSAGES 

pathname, is not a directory 
A pathname exists but is not a directory. 

pathname, directory does not exist 

The pathname does not exist, either as a directory or as a data file. 

pathname, directory LIST access required 
You do not have list access to the directory. 


DIR COMMAND EXAMPLES 


The examples that follow show how a directory's files are listed when you 
use your configured system's default prefix in a directory's pathname. 

In the exanples, directory names are enclosed in triangles; data file 
names are enclosed in rectangles. 

Assume you have the following directory structure for your files: 
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DIR COMMAtID EXAMPLES (continued) 



Exanqple 1: 

If your default prefix was :FO;/Q, then the following files would be 
listed in response to the DIR pathname entry exanq)les in the 
following "Pathname" column: 


Pathname 


Files Listed 


omitted 

f 

A, f 

not allowed 

because 

f 

is 

a 

data 

file 

A 

A/d 

bb, CB, d 
not allowed 

because 

d 

is 

a 

data 

file 

A/CB 

A/CB/e 

e, f 

not allowed 

because 

e 

is 

a 

data 

file 


Exanq[>le 2 : 

If your default prefix was :FO;/Q/A, then the following files would 
be listed in response to the DIR pathname entry examples in the 
following "Pathname" column: 


Pathname 


Files Listed 


omitted 

A 

CB 


bb, CB, d 

not allowed because directory A does not 
contain an entry A 
e, f 
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DIR LISTING FORMATS 


Figures 3-1, 3-2, 3-3, and 3-4 show output exanq)les for EXTENDED, FAST, 
LONG, and SHORT listing formats respectively. Table 3-2 defines the 
displayed column headings. 


(column scale only) 

1 2 3 4 5 6 7 

1 2 34 567890 1 2 34 567890 1234 567890 1234 567890 12345678901 234 567fi90 12 34 567890 1234 56789 


DIRECTORY OF 

sys 

ON myvol 













GRAN 




NAME 

AT 

ACC 

BLKS 

LENGTH 

VOL 

FIL 

OWNER 

LAST MOD 

ed 


DR 

200 

30185 

16 

3 

Beck 


20 NOV 79 





CREATION: 

20 

APR 

78 

ACCESSORS 

ACC 





LAST ACC: 

25 

NOV 

79 

Eng ineers 

R 









Techs 

II 

id isk 

DR 

DLAC 

5 

39 

16 

1 

WORLD 

12 DEC 79 





CREATION: 

15 

NOV 

78 

ACCESSORS 

ACC 





LAST ACC: 

10 

JAN 

80 



submi t$plm$ab 

MA 

DRAU 

11 

1057 

24 

2 

BACKWORDPLMCOM 

16 JUN 79 





CREATION: 

20 

APR 

78 

ACCESSORS 

ACC 





LAST ACC: 

20 

JAN 

80 

PYE-WACKET 

' All 









TOGAN 

R 









longlongnamess D U 

CHAOTICGOOD 


U 123456789 

1234567890 12345 

123 

Chopin 

01 DEC 79 





CREATION: 

16 

NOV 

79 

ACCESSORS 

ACC 





LAST ACC: 

20 

FEB 

80 

Clerics 

RA 









MAGIC-USERS U 









Th i eves 

D 









FIGHTERS 

DRAU 

LAWFULEVIL 


D 

73 

9081 

24 

1 5 

saveyourha t 

04 JAN 80 





CREATION: 

15 

NOV 

79 

ACCESSORS 

ACC 





LAST ACC: 

05 

MAR 

80 

WORLD 

RAU 


5 FILES 1839 BLOCKS 1200453 BYTES 


Figure 3-1. EXTENDED Directory Listing Exanq)le^ 


03/11/80 04:25:40 

DIRECTORY OF alpha ON mvol 
fnamel fname2 fname3 fname4 
fname6 fname7 fnameS fname9 
fnamel 1 ... 


f name 5 
f name 10 


Figure 3-2. FAST Directory Listing Example 
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DIR LISTING FORMATS (continued) 


(column scale only) 

1 2 3 4 5 6 7 

1234567890123456789012345678901234567890123456789012345678901234567890123456789 


11 JAN 80 06:30:30 

DIRECTORY OF sys ON myvol 

GRAN 


NAME 

AT 

ACC 

BLKS 

LENGTH 

VOL 

FLL 

OWNER 

LAST MOD 

ed 


DR 

200 

30185 

16 

3 

BECK 

20 

NOV 

79 

idisk 

DR 

DLAC 

5 

39 

16 

1 

WORLD 

12 

DEC 

79 

LEMONADEIT 

MA 

D 

105 

13074 

64 

2 

malag i 

16 

MAR 

77 

credit 


DR 

263 

32967 

128 

6 

WORLD 

17 

NOV 

79 

SUBMITAGAINPLM 

MA 

DRAU 

11 

1057 

24 

2 

BACKWORDPLMCOM 

16 

JUN 

79 

type 

DR 

LA 

4 

365 

16 

1 

PASCAL 

15 

DEC 

79 

CHAOTICGOOD 


U 

123456789 

1234567890 

12345 

123 

CHOPIN 

01 

DEC 

79 

LAWFULEVIL 


D 

73 

9081 

24 

15 

saveyourpet 

04 

JAN 

80 


8 FILES 1839 BLOCKS 1200453 BYTES 


Figure 3-3. LONG Directory Listing Example 


(column scale only) 

1 2 3 4 5 6 7 

1234567890123456789012345678901234567890123456789012345678901234567890123456789 


03/11/80 04:25:50 


DIRECTORY OF sys ON myvol 


NAME 

AT 

ACC 

BLKS 

LENGTH 

NAME 

AT 

ACC 

BLKS 

LENGTH 

append 


R 

40 

1425 

attr ib 


DRAU 

38 

4682 

COPY 

MA 

DRAU 

65 

8042 

CREDIT. HAZ 


R 

263 

33017 

dcopy 


DRAU 

62 

7718 

DELETE 


A 

37 

4506 

REFERENCE 

DR 

L 

5 

10 

DATA 

DR 

DLAC 

1 

4 

DUMP 


D 

22 

2568 

ED 


DR 

200 

30185 

idisk 

DR 

DLAC 

5 

39 






LEMONADEIT 

MA 

D 

123456789 1234567890 





CREDIT 


DR 

263 

32967 

RENAME 


AU 

21 

2487 

submi t$plm 

MA 

DRAU 

11 

057 

TYPE 

DR 

LA 

4 

366 

CHAOTICGOOD 


U 

13293 

1151640 

lawf ulevil 


D 

73 

9081 

18 FILES 


1839 B 

LOCKS 

1200453 

BYTES 






Figure 3-4. SHORT Directory Listing Example 
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Table 3-2. Directory Listing Headings 


Heading 


Meaning 


NAME: 


14-character file NAME 


AT: 


File ATtribute, where: 

DR = Directory (if the ATtribute field is blank, the 
file is a data file) 


ACC: 


File ACCess rights, where: 


Directories: 


DLAC 


Delete 

List 

Add 

Change 


BLKS: 


LENGTH: 

VOL: 

FIL: 

OWNER: 


DRAU 


Other Files: 


Update 

Append 

Read 

Delete 


Nine-digit number (five digits on SHORT listing) giving the 
volume -granularity units allocated to the file. On the 
SHORT form, if the number of digits exceeds five, the file 
is displayed in the nine-digit form (see the LEMONADEIT 
file in Figure 3-4). 


10-digit number (7 digits on SHORT listing) giving the 
length of the file in bytes. On the SHORT form, if the 
number of digits exceeds 7, the file is displayed in the 
10-digit form (see the LEMONADIT file in Figure 3-4). 

Five-digit number giving the volume granularity in bytes. 


Three-digit number giving the granularity of the file in 
volume-granularity units. 

14-character, alphanumeric owner name. 


LAST MOD: 


Date of last file modification. 


LAST ACC: 
CREATION: 
ACCESSORS: 
ACC: 


Date of last file access. 

Date of file creation. 

Heading for list of 14 -character accessor names. 

Heading for access rights of file accessors. The format of 
this field is identical to ACC above. 
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DISKVERIFY 


This command invokes the disk verification utility which verifies the 
data structures of iRMX 86 physical and named volumes. This utility can 
also be used to reconstruct portions of the volume and perform absolute 
editing on the volume. The format of the DISKVERIFY command is as 
f ollows : 



INPUT PARAMETERS 

: logical-name: Logical name of the secondary storage device 

containing the volume. 

VERIFY or V Performs a verification of the volume. If you 

specify this parameter and omit the options, the 
utility performs the NAMED verification. 

If you specify this parameter, the utility 
performs the verification function and returns 
control to you at the Human Interface level. You 
can then enter any Human Interface command. 

If you omit this parameter, the utility displays a 
sign-on message and the utility prompt (*). You 
can then enter Individual disk verification 
commands. These commands are described in the 
IRMX 86 DISK VERIFICATION UTILITY REFERENCE MANUAL. 
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INPUT PARAMETERS (continued) 

NAMEDl or N1 VERIFY option that applies to named volumes only. 

This option checks the f nodes of the volume to 
ensure that they match the directories in terms of 
file type and file heirarchy. This option also 
checks the information in each fnode to ensure 
that it is consistent. As a result of this 
option, DISKVERIFY displays a list of all files on 
the volume that are in error, with information 
about each file. Refer to the iRMX 86 DISK 
VERIFICATION UTILITY REFERENCE MANUAL for more 
information. 

NAMED2 or N2 VERIFY option that applies to named volumes only. 

This option checks the allocation of fnodes on the 
volume, checks the allocation of space on the 
volume, and verifies that the fnodes point to the 
correct locations on the volume. Refer to the 
iRMX 86 DISK VERIFICATION UTILITY REFERENCE MANUAL 
for more information. 

NAMED or N VERIFY option that performs both the NAMEDl and 

NAMED2 verification functions on a named volume. 

If you omit the VERIFY option, NAMED is the 
default option. 

PHYSICAL VERIFY option that applies to both named and 

physical volumes. This option reads all blocks on 
the volume and checks for I/O errors. 

ALL VERIFY option that applies to both named and 

physical volumes. For named volumes, this option 
performs both the NAMED and PHYSICAL verification 
functions. For physical volumes, this option 
performs the PHYSICAL verification function. 


OUTPUT PARAMETERS 

TO Copies the output from the disk verification 

utility to the specified file. If no preposition 
is specified, TO :C0: is the default. 

OVER Copies the output from the disk verification 

utility over the specified file. 

AFTER Appends the output from the disk verification 

utility to the end of the specified file. 


3-33 


DISKVERIFY 


OUTPUT PARAMETERS (continued) 

outpath Pathname of the file to receive the output from 

the disk verification utility. If you omit this 
parameter and the TO/OVER/AFTER preposition, the 
utility copies the output to the console screen 
(TO :C0:). You cannot direct the output to a file 
on the volume being verified. If you attempt 
this, the utility returns an E$NOT_CONNECTED error 
message. 


DESCRIPTION 

When you enter the DISKVERIFY command, the utility responds by displaying 
the following line: 

iRMX 86 DISK VERIFY UTILITY, Vx.x 

where Vx.x is the version number of the utility. If you specify the 
VERIFY or V parameter in the DISKVERIFY command, the utility performs a 
verification of the volume and copies the verification information to the 
console (or to the file specified by the outpath parameter). Refer to 
the iRMX 86 DISK VERIFICATION UTILITY REFERENCE MANUAL for a description 
of the verification output. After generating the verification output, 
the utility returns control to the Human Interface, which prompts you for 
more Human Interface commands. The following is an exan 5 )le of such a 
DISKVERIFY command; 

-DISKVERIFY ;Fl: VERIFY NAMED2 
iRMX 86 DISK VERIFY UTILITY , Vx.x 

DEVICE NAME = Fl : DEVICE SIZE = 0003E900 ; BLOCK SIZE = 0080 

’NAMED2* VERIFICATION 
BIT MAPS O.K. 


However, if you omit the VERIFY (or V) parameter from the DISKVERIFY 
command, the utility does not return control to the Human Interface. 
Instead, it issues an asterisk (*) as a prompt and waits for you to enter 
individual DISKVERIFY commands. The following is an example of such a 
DISKVERIFY command: 

-DISKVERIFY :F1: 

* 

After you receive the asterisk prompt, you can enter any of the 
DISKVERIFY commands listed in the IRMX 86 DISK VERIFICATION UTILITY 
REFERENCE MANUAL. 
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ERROR MESSAGES 

logical name, 0045 : E$LOG_NAME_NEXIST 

You specified a nonexistent logical name in either the : logical name: 
parameter or the outpath parameter. 


8042 : E$N0T_C0NNECTI0N 

You attempted to direct output to a file on the volume being verified. 


command line error 

You made a syntax error when entering the command. 


device size inconsistent 

size in volume label = valuel ; computed size = value2 

When the disk verification utility computed the size of the volume, the 
size it computed did not match the information recorded in the iRMX 86 
volume label. It is likely that the volume label contains invalid or 
corrupted information. This error is not a fatal error, but it is an 
indication that further error conditions may result during the 
verification session. You may have to reformat the volume or use the 
disk verification utility to modify the volume label. Refer to the iRMX 
86 DISK VERIFICATION UTILITY REFERENCE MANUAL for more Information about 
the disk verification utility commands. 


logical name, illegal logical name 
The logical name you specified was not surrounded by colons (:). 


not a named disk 

You tried to perform a NAMED, NAMEDl, or NAMED2 verification on a 
physical volume. 


ver if y-f unction argument error 
The VERIFY option you specified is not valid. 


The NAMEDl, NAMED2, and PHYSICAL verification options can also produce 
error messages. Refer to the iRMX 86 DISK VERIFICATION UTILITY REFERENCE 
MANUAL for more information about these messages. 
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EXAMPLE 

The following command performs both named and physical verification of a 
named volume. 

-DISKVERIFY ;Fl; VERIFY ALL 

DEVICE NAME = FI : DEVICE SIZE = 0003E900 : BLK SIZE = 0080 

*NAtIEDl' VERIFICATION 

*NAMED2' VERIFICATION 
BIT MAPS O.K. 

’PHYSICAL* VERIFICATION 
NO ERRORS 
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DOIWCOPY 


This command copies files from a volume on an iRMX 86 secondary storage 
device to a volume on an ISIS-II secondary storage device via the 
iSBC 957A/B Interface and Execution package. The format is as follows: 



INPUT PARAMETERS 

inpath-list One or more iRMX 86 pathnames for files, separated 

by commas, that are to be copied to ISIS-II 
secondary storage. Separating blanks between 
pathnames are optional. The files may be copied 
in the listed sequence either on a one-for-one 
basis or concatenated into one or more files. 

QUERY Causes the Human Interface to pronqpt for 

permission to copy each IRMX 86 file to the listed 
ISIS-II destination file. Depending on which 
preposition you specify (TO, OVER, or AFTER), the 
Human Interface prompts with one of the following 
queries: 

pathname, copy down TO out-pathname? 
pathname, copy down OVER out-pathname? 
pathname, copy down AFTER out-pathndme? 


Enter one of 
query: 

the following in response 

to the 

Entry 

Action 


Y or y 

Copy the file. 


E or e 

Exit from the DOWNCOPY 

command 

R or r 

Continue copying files 
further query. 

without 

Any other 

Do not copy this file; 

query 

character 

for the next file in sequence. 
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OUTPUT PARAMETERS 

TO Reads IRMX 86 files and copies them TO new ISIS-II 

files in the listed sequence. The specified 
output files should not already exist in the 
ISIS-II directory when the TO parameter is used. 

If a named output file does exist, DOIWCOPY will 
display the following message: 

filename, already exists, delete? 

Enter a Y or y if you wish to delete the existing 
file. Enter any other character if you do not 
wish the existing file to be deleted. 

If no preposition is specified, TO :C0: (ISIS-II 
console screen) is the default. If more input 
files than output files are specified, the 
remaining input files will be appended to the end 
of the last listed ISIS-II file. 

OVER Reads the listed iRMX 86 input files and copies 

them OVER the existing ISIS-II destination files 
in the listed sequence. If more input files than 
output files are listed, the remaining input files 
will be appended to the end of the last listed 
ISIS-II file. 

AFTER Reads the listed IRMX 86 input files and copies 

them AFTER the end of data on the existing ISIS-II 
destination files in the listed sequence. 

outfile-llst One or more ISIS-II filenames for the output 

files. Multiple filenames must be separated by 
commas. Separating blanks are optional. If the 
preposition and output file defaults are used in 
the command line, the output will go to the 
ISIS-II console screen. 


DESCRIPTION 

The DOWNCOPY command cannot be used to copy directories from an IRMX 86 
system to an ISIS-II system; only files can be copied. 

Before you enter a DOWNCOPY command on the iRMX 86 console keyboard, you 
must have your target system connected to a development system with the 
957A/B package, and the package must be running. The ISIS-II copies of 
the files will have all ISIS-II file attributes turned off. 

As each file in the input list is copied, one of the following messages 
will be displayed on the Human Interface console output device (:C0;), as 
appropriate: 
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DESCRIPTION (continued) 
pathname, copied 
pathname, copied 
pathname, copied 


down TO out-filename 
down OVER out -filename 
down AFTER out-filename 


3-39 



FORMAT 


FORMAT 


This command formats or reformats a volume on an iRMX 86 secondary 
storage device, such as a diskette, hard disk, or bubble memory. 

The format is as follows: 



INPUT PARAMETERS 

: logical-name: Logical name of the physical device-unit to be 

formatted. The logical name must be preceded and 
followed by colons without embedded blanks between 
the logical name and volume name. 

volume-name Six-character, alphanumeric ASCII name, without 

embedded blanks, to be assigned to the volume. 

(See the definition for a "volume" in Chapter 1.) 

FNODES=num Defines the maximum decimal number of files that 

may be created on a NAMED volume. (This parameter 
is not meaningful when formatting a PHYSICAL 
volume and will be ignored if specified for such 
volumes.) The range is 7 through 32,767 fnodes, 
although the maximum number of fnodes you can 
define depends on the settings of the GRANULARITY 
and EXTENSIONSIZE parameters (as explained in the 
"Description" portion of this command write-up). 

If not specified, the default is 50 fnodes. 

GRANULARITY=num Volume granularity; the minimum number of bytes to 

be allocated for each Increment of file size on a 
NAMED volume. (This parameter is not meaningful 
for PHYSICAL volumes, and will be ignored if 
specified for such volumes.) The specified 
decimal number is placed in the header of the 
volume and becomes the default file granularity 
when a file is created on the volume. 
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INPUT PARAMETERS 

GRANULARITY=num (continued) 

The range Is 1 through 65,535 (decimal) bytes, 
although the maximum allowable volume granularity 
depends on the settings of the FNODES and 
EXTENSIONSIZE parameters (as explained in the 
"Description" portion of this write-up). If not 
specified, the default granularity is the device 
granualarity. Once the volume granularity is 
defined, it applies to every file created on that 
VO lume . 

EXTENS IONS IZE=n urn Size, in bytes, of the extension data portion of 

each file descriptor node (fnode). (This 
parameter is not meaningful for PHYSICAL volumes, 
and will be ignored if specified for such 
volumes.) The range is 0 through 65,448 
(decimal), although the maximum allowable 
extension size depends on the settings of the 
FNODES and GRANULARITY parameters (as explained in 
the "Description" portion of this write-up). If 
not specified, the default extension size is 3 
bytes. 

INTERLEAVE=num Interleave factor for a NAMED or PHYSICAL volume. 

If not specified, the default value is 5, which is 
the optimum interleave factor for an iSBC 204 
bootstrap load. See the Interleave discussion 
under "Description" in this command write-up. 

NAMED The volume can store only named files; that is, 

the volume can hold many files (up to the number 
of f nodes allocated), each of which can be 
accessed by its pathname. A diskette or hard disk 
surface are exanqjles of devices that would be 
formatted for named files. If neither NAMED nor 
PHYSICAL is specified, the volume is formatted for 
the type of files specified when you attached the 
device (with the ATTACHDEVICE command). 

PHYSICAL The volume can be used only as a single, physical 

file. The GRANULARITY and FNODES parameters are 
not meaningful when PHYSICAL is specified for the 
volume. If neither NAMED nor PHYSICAL is 
specified, the volume is formatted for the type of 
files specified when you attached the device (with 
the ATTACHDEVICE command). 
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DESCRIPTION 

Every physical device-unit used for secondary storage must be formatted 
before it can be used for storing and then accessing its files. For 
exan^)le, every time you mount a previously unused diskette into a drive, 
you must enter a FORMAT command to format that diskette as a new volume 
before you can create, store and access files on it. 

Once a volume is formatted, its name becomes a volume identifier when you 
list the root directory for the volume, and the name will appear in the 
directory’s heading. Although the Human Interface uses the volume name 
in its own internal processing when you access the volume, you do not 
need to specify the volume name in any subsequent command after the 
volume is formatted; only the logical name of the secondary storage 
device on which the volume is currently mounted needs to be specified. 

The number of f nodes on a volume defines the number of files that can 
exist on the volume. You can specify this number with with the FNODES 
parameter. Each fnode is a data structure that contains information 
about a file. Each time you create a file on the volume, the Operating 
System records information about the file in an unused fnode. Later, it 
uses the fnode in order to determine the location of the file on the 
volume. 

Each fnode contains a field that stores extension data for its associated 
file. An operating system extension can access and modify this extension 
data by invoking the A$GET$EXTENSION$DATA and A$SET$EXTENSION$DATA system 
calls (refer to the iRMX 86 SYSTEM PROGRAMMER’S REFERENCE MANUAL for more 
information). When you format a volume, you can use the EXTENSIONSIZE 
parameter to set the size of the extension data field in each fnode. 
Although you can specify any size from 0 to 65,448 bytes, the Human 
Interface requires all f nodes to have at least 2 bytes of extension data. 

The default volume granularity is always the granularity of the physical 
device for the volume. For example, if the default granularity for a 
device is 128 bytes of secondary storage, the I/O System will 
automatically allocate 128 bytes of permanent storage to each new file 
you create on that volume, regardless of whether or not a file requires a 
full 128 bytes. If the size of a file exceeds 128 bytes, the I/O System 
will allocate still another full block of 128 bytes, and so on, until the 
volume is full. 

Although the FNODES, GRANULARITY, and EXTENSIONSIZE parameters have 
maximum values which are listed in the parameter descriptions, the 
combination of these three parameters must also satisfy the following 
formula: 

(87 + EXTENSIONSIZE) x FNODES / GRANULARITY < 65535 

where all numbers are decimal. FORMAT displays an error message if the 
combination of parameter values exceeds the limit. 
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As stated previously, the interleave factor applies to volumes formatted 
either for NAMED or PHYSICAL files* The Interleave specification 
maximizes access speed for the files on a given volume, depending on the 
intent of volume and the device configuration. For example, an 
interleave factor of 5 for a flexible disk drive means that, for each 
file, the I/O System will read every fifth sector on the diskette, 
starting with an index of 1 (other, hard disk systems may be different, 
depending on your configuration). Therefore, the I/O System does not 
need to wait for the disk to make a complete revolution before it 
accesses the next sector; the next sector by an increment of 5 is ready 
to be accessed for read/ write by the time the previously accessed sector 
has been processed. 

The FORMAT command displays the following message when volume formatting 
is completed; 

volume (vol-name) will be formatted as a NAMED/ PHYSICAL volume 
granularity = number 
Interleave = number 
numbe rf nodes = number 
extensionsize = number 


where: 

vol-name The volume name specified in the FORMAT command. 

NAMED/PHYSICAL Either NAMED or PHYSICAL will be displayed in the 

message, depending on the command specification. 

number Default or specifically defined in the command. 


ERROR MESSAGES 

If a device cannot be detached for formatting, the following message is 
displayed on the user console: 

logical-name, can*t detach device 

which means that the volume does not exist, the volume is busy, or the 
device on which the volume is mounted is not currently attached to the 
system. 

If the device cannot be attached for formatting, or it cannot be 
re-attached (e.g., restored to its original configuration prior to 
formatting) after formatting takes place, the following message is 
displayed on the user console: 

device-name, can't attach device 



FORMAT 


ERROR MESSAGES (continued) 

The following error message is displayed if you atten 5 )t to format 
something that is not a physical device: 

logical-name, is not a device connection 

Tlie following error message is displayed if you specify a volume name 
containing more than six ASCII characters or if you specify a logical 
device name: 

vol-name, illegal name 

The following error message is displayed if you specify an out-of-range 
number for any of the FNODES, GRANULARITY, EXTENSIONSIZE, or INTERLEAVE 
parameters: 

number, illegal number 

The following message is displayed if the values you specify for fnode 
size, granularity, and extension data size cause the formula listed in 
the "Description" section to exceed its limit. 

vol-name, fnode file size exceeds 65535 volume blocks 
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RENAME 


This command allows you to change the pathname of one or more data files 
or directories. RENAME is effective across directory boundaries on the 
same volume. The format is as follows: 



INPUT PARAMETERS 

inpath-list One or more pathnames, separated by commas, of 

files or directories that are to be renamed. 
Blanks between pathnames are optional separators. 

QUERY Causes the Human Interface to prompt for 

permission to rename each pathname in the input 
list by issuing the following message: 

oldname, RENAME? 


Enter one of the following (followed by a carraige 
return) in response to the query: 


Entry 

Action 


Y or y 

Rename the file. 


E or e 

Exit from RENAME command. 


R or r 

Continue renaming without 
query . 

further 

Any other 

Do not rename file; query 

for the next 

character 

file in sequence. 



OUTPUT PARAMETERS 

TO Moves the data to the new pathnames in the output 

list. A new pathname in the output list should 
not already exist. If, in fact, a new pathname 
does already exist, RENAME displays the following 
warning message when the pre-existing pathname is 
encountered: 

pathname, already exists, DELETE? 
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OUTPUT PARAMETERS 

TO (continued) Enter a "Y" or "y" if you wish the pre-existing 

pathname and its contents to be written over by the 
new name specification. The pre-existing pathname 
and its contents will be deleted. 

Enter any other character if you do not wish the 
pre-existing file to be deleted. Renaming of the 
specified file will not take place and the RENAME 
command will atteii5)t to rename the next pathname in 
the list sequence. 

OVER Changes each old pathname in a list to the 

corresponding new pathname, even if the new pathname 
already exists. The old pathname is deleted from 
secondary storage. OVER cannot be used to rename a 
non-empty directory over another non-empty 
directory. 

outpath-llst List of new pathnames. Multiple pathnames must be 

separated by commas. Separating blanks are optional. 


DESCRIPTION 

The primary distinction between the RENAME command and the COPY command is 
that, as a RENAME command is executed, it releases the pathnames in the 
listed input files for new uses without having to perform any further 
operation on the files. 

Although RENAME can be used to rename an existing directory pathname TO a 
new pathname, it cannot be used to rename an existing directory OVER 
another existing directory. For exanq)le; 

-rename ALPHA to DELTA allowed 

-rename ALPHA over BETA not allowed (unless BETA is empty) 

-rename ALPHA /sampl over BETA/testl allowed 


CAUTION 

Note that changing the name of a 
directory also changes the path of all 
files listed under that directory. All 
subsequent accesses to those files must 
specify the new pathnames for the files. 


As each file in a pathname list is renamed, the RENAME command displays 
one of the following messages, as appropriate; 

old-pathname, renamed TO new-pathname 

or 

old-pathname, renamed OVER new-pathname 
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ERROR MESSAGES 

There must be a one-for-one correspondence between the oldname and 
newname lists in the RENAME command* A missing element in either list 
causes RENAME to display the following message: 

unmatched path name lists 

If your system is configured with user-designed access limitations, you 
must have at least delete access to old pathnames and add-entry access to 
the destination directory to use the RENAME command* 

If you are not allowed delete access on your system, the following 
message is displayed when you atten?>t to use the OVER preposition in a 
RENAME command: 

old-pathname, DELETE access required 

If you are not allowed add-entry access on your system, the following 
message is displayed when you attempt to use the TO preposition in a 
RENAME command: 

new-pathname, directory ADD ENTRY access required 

If the RENAME command encounters an error in the renaming of a file, it 
will atten 5 )t to continue renaming each succeeding file in sequence* 

Use of the AFTER preposition is not valid for the RENAME command, and an 
attempt to use it causes the following message to be displayed: 

AFTER preposition, TO or OVER preposition expected 

Note that the RENAME command is the only Human Interface file handling 
command that cannot be used across volume boundaries; that is, you cannot 
use the RENAME command to rename a file or move data from a 'volume 
located on one secondary storage device to a volume located on another 
secondary storage device (e*g, , from one diskette to another). An 
attempt to do so causes the following error message: 

0005: E$C0NTEXT 

Use the COPY command or a combination of COPY and DELETE commands if you 
wish to ren^e files or move data across volume boundaries. 
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RESTORE 

This command restores files to a named volume by copying them from a 
backup volume. 

The format of this command is as follows; 



INPUT PARAMETERS 

:backup device; Logical name of the backup device from which 

RESTORE restores files. 

QUERY Causes the Human Interface to prompt for 

permission to restore each file. The Human 
Interface pron5>ts with one of the following 
queries; 

pathname, RESTORE data file? 
or 


pathname, RESTORE directory? 

Enter one of the following responses to the query; 


Entry 

Action 

Y or y 

Restore the file. 

E or e 

Exit from the RESTORE command. 

R or r 

Continue restoring files without 
further query. 

Any other 

If data file, do not restore the 

character 

file; if directory file, do not 
restore the directory or any 
file in that portion of the 
directory tree. Query for the 
next file, if any. 
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OUTPUT PARAMETERS 
TO 


OVER 


pathname 


Restores the files from the backup volume to new 
files on the named volume, if the files do not 
already exist on the named volume. However, if a 
file being restored already exists on the named 
volume, RESTORE prompts for permission to restore 
the file. 

Restores the files from the backup volume over 
(replaces) the files on the named volume. If a 
file does not exist on the named volume, RESTORE 
creates a new file on the named volume. 

Pathname of a file which receives the restored 
files (you must specify a directory pathname when 
restoring more than one file). If you specify a 
logical name for a device, RESTORE places the 
files under the root directory for that device. 
However, the device must contain a volume 
formatted as a named volume. If you wish to 
restore files to the directory in which they 
originated, you should specify the same pathname 
parameter as you used with the BACKUP command. 


DESCRIPTION 

RESTORE is a utility which copies files from backup volumes (where the 
BACKUP command originally saved them) to named volumes. RESTORE copies 
the files to any directory you specify, maintaining the hierarchical 
relationships between the backed-up files. 

When RESTORE copies files, it copies only those files for which you are 
the owner. For these files, it restores the following information: 

• File name 

• Access list 

• Extension data 

• File granularity 

• Contents of the file 

RESTORE changes the creation, last modification, and last access dates of 
the file to the current date. 

Each backup volume which is used as input to the RESTORE command must 
contain files placed there by the BACKUP command. In addition, if the 
backup operation required multiple backup volumes, you must restore these 
volumes in the same order as they were backed up. 
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DESCRIPTION (continued) 

The output volume which receives the restored files must be a named 
volume. You must have sufficient access rights to the files in that 
volume to allow RESTORE to perform all necessary operations. In order 
for RESTORE to create new files on a named volume, you must have add 
entry access to directories on that volume. In order for RESTORE to 
restore files over existing files, you must have add entry and change 
entry access to directories ih that volume and delete, append, and update 
access to data files. 

When you enter the RESTORE command, RESTORE displays the following 
sign-on message: 

iRMX 86 DISK RESTORE UTILITY Vx.x 

where Vx.x is the version number of the utility. Then it prompts you for 
a backup volume. 

Whenever RESTORE requires a new backup volume, it issues the following 
message: 

backup device, mount backup volume /i^nn, enter Y to continue: 

where backup device indicates the logical name of the backup device and 
nn the number of the requested volume. (RESTORE in some cases displays 
additional information to indicate problems with the current volume.) In 
response to this message, place the backup volume in the backup device 
(make sure that the volume number is correct if the backup operation 
Involved multiple volumes). Enter one of the following: 

Entry Action 

Y, y, R, or r Continue the restore process. 

E or e Exit from the RESTORE command. 

Any other Invalid entry; reprompt for entry, 

character 

RESTORE continues prompting you until you supply the correct backup 
volume. 

As it restores each file, RESTORE displays the following message at the 
Human Interface console output device (:C0:): 

pathname, RESTORED 

However, if a file with the same pathname already exists during a restore 
operation using the TO preposition, RESTORE displays the following 
message: 

pathname, already exists, DELETE? 
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DESCRIPTION (continued) 


Enter one of the following in response to the query: 


Entry 
Y or y 

E or e 


Action 

Delete the file and replace it with the one from 
the backup volume. 

Exit from the RESTORE command. 


R or r Delete the file, replace it with the one from the 

backup volume, and continue restoring files 
without further queries. 

Any other Do not restore the file; go on to the next file, 

character 


ERROR MESSAGES 

pathname, ADD ENTRY or UPDATE access required 

RESTORE could not restore a file, either because you did not have add 
entry access to the file's parent directory or because you did not have 
update access to the file. RESTORE continues with the next file. 


backup device, backup volume //nn, date, mounted 
backup device, backup volume #nn, date, required 

backup device, mount backup volume #nn, enter Y to continue: 

RESTORE cannot continue because the backup volume you supplied is not the 
one that RESTORE expected. Either you supplied a volume out of order or 
you supplied a volume from a different backup session. RESTORE repron 5 >ts 
for the correct backup volume. 


backup device, cannot attach volume 
backup device, exception code 

backup device, mount backup volume #nn, enter Y to continue: 

RESTORE cannot access the backup volume. This could be because there is 
no volume in the backup device, the volume is write protected, or because 
of a hardware problem with the device. The second line of the message 
indicates the iRMX 86 exception code encountered. RESTORE continues to 
issue this message until you supply a volume that RESTORE can access. 
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ERROR MESSAGES (continued) 

pathname, DELETE access required 

RESTORE could not restore a file because you did not have delete access 
to the file. RESTORE continues with the next file. 


pathname, exception code, error during BACKUP, file not restored 

When the BACKUP utility saved files, it encountered an error when 
atteii 5 >ting to save the file Indicated by this pathname. RESTORE is 
unable to restore this file. The message lists the iRMX 86 exception 
code encountered. 


pathname, exception code, error during BACKUP, restore incomplete 

When the BACKUP utility saved the files, it encountered an error when 
atten^>ting to save the file indicated by this pathname. RESTORE restores 
as much of the file as possible to the named volume. The message lists 
the iRMX 86 exception code encountered. 


backup device, error reading backup volume 
backup device, exception code 

RESTORE tried to read the backup volume but encountered an error 
condition, possibly because of a faulty area on the volume. The second 
line of the message indicates the iRMX 86 exception code encountered. 


pathname, exception code, error writing output file, restore incomplete 

RESTORE encountered an error while writing a file to the named volume. 

This message lists the iRMX 86 exception code encountered. RESTORE 
writes as much of the file as possible to the named volume. 


pathname, extension data not con 5 >letely restored, nn bytes required 

The amount of space available on the named volume for extension data is 
not sufficient to contain all the extension data associated with the 
specified file. The value nn indicates the number of bytes required to 
contain all the extension data. This message indicates that the named 
volume on which RESTORE is restoring files is formatted differently than 
the named volume which originally contained the files. RESTORE restores 
as much of the extension data as possible. To ensure that you restore 
all the extension data from the backup volume, you should restore the 
files to a volume formatted with an extension size set equal to the 
largest value reported in any message of this kind. Refer to the 
description of the FORMAT command for information about setting the 
extension size. 
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ERROR MESSAGES (continued) 

pathname, file does not exist 

The pathname you specified as input to RESTORE does not represent an 
existing file or device. 

pathname, file not restored 

For some reason, RESTORE was unable to restore a file from the backup 
volume. RESTORE continues with the next file. Another message usually 
precedes this message to indicate the reason for not restoring the file. 


backup device, invalid logical name 

The logical name you specified for the backup device contains unmatched 
colons, is longer than 12 characters, contains invalid characters, or 
does not exist. 


backup device, not a backup volume 

backup device, mount backup volume //nn, enter Y to continue: 

The volume you supplied on the backup device was not a backup volume. 
RESTORE continues to issue this message until you supply a backup volume. 

backup device, not a valid backup device 

The logical name you specified for the backup device was not a logical 
name for a device. 

output specification missing 

You did not specify a pathname to indicate the destination of the 
restored files. 

pathname, READ access required 

You do not have read access to a file on the backup volume; therefore 
RESTORE cannot restore the file. 

keyword, too many values 

You specified too many values after the TO or OVER parameter. 
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ERROR MESSAGES (continued) 

keyword, unrecognized control 

You entered an invalid optional parameter. The keyword portion of the 
message indicates the parameter that is in error. 


pathname, exception code 

The pathname you specified as input to RESTORE is in error. This error 
could occur if you specify an invalid or nonexistent path component. 
This message displays the exception code that results from this error. 
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This command reads and executes a set of commands from a file in 
secondary storage instead of from the console keyboard. To use the 
SUBMIT command you must first create a data file that defines the command 
sequence and formal parameters (if any). 

The format of the command is as follows: 



INPUT PARAMETERS 

pathname Name of the file from which the commands x^ill be 

read. This file may contain nested SUBMIT files. 

parameter-list Actual parameters that are to replace the formal 

parameters in the SUBMIT file. You must surround 
this parameter list with parentheses. You can 
specify as many as 10 parameters, separated by 
commas, in the SUBMIT command. If you omit a 
parameter, you must reserve its position by 
entering a comma. If a parameter contains a 
comma, space, or parenthesis, you must enclose the 
parameter in single quotes. The sum of all 
characters in the parameter list must not exceed 
512 characters. 


OUTPUT PARAMETERS 

TO Causes the output from each command in the SUBMIT 

file to be written to the specified new file 
instead of the console screen. If the listed 
output file already exists, the SUBMIT command 
will display the following message: 

pathname, already exists DELETE? 

Enter a Y or y if you wish the existing output 
file to be deleted. Enter any other character if 
you do not wish the existing file to be deleted. 

A response other than Y or y causes the SUBMIT 
command to be terminated and you will be prompted 
for a new command entry. 
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OUTPUT PARAMETERS (continued) 


OVER 


AFTER 


outpath-llst 


Causes the output for each command in the SUBMIT 
file to be written over the specified existing 
file instead of the console screen. 

Causes the output from each command in the SUBMIT 
file to be written to the end of an existing file 
instead of the console screen. 

Pathnames of one or more files to receive the 
processed output from each command executed from 
the SUBMIT file. If no preposition or output file 
is specified, TO :C0: is the default. 


DESCRIPTION 

Any program that reads its commands from the console keyboard can be 
executed from a SUBMIT file. If another SUBMIT command is Itself used in 
a SUBMIT file, it causes another SUBMIT file to be invoked. You can nest 
SUBMIT files to any level of nesting until memory is exhausted. When one 
nested SUBMIT file completes execution, it returns control to the next 
higher level of SUBMIT file. 

When you create a SUBMIT file, you indicate formal parameters by 
specifying the characters %n, where n ranges from 0 through 9. When 
SUBMIT executes the file, it replaces the formal parameters with the 
actual parameters listed in the SUBMIT command (the first parameter 
replaces all Instances of %0, the second parameter replaces all instances 
of %1, and so forth). If the actual parameter is surrounded by quotes, 
SUBMIT removes the quotes before performing the substitution. If there 
is no actual parameter that corresponds to a formal parameter, SUBMIT 
replaces the formal parameter with a null string. 

When you specify a preposition and output file in a SUBMIT command, only 
your SUBMIT command entry will be echoed on the console screen; the 
individual command entries in the submit file are not displayed on the 
screen as they are loaded and executed. 

The SUBMIT command will display the following message when all commands 
in the submit file have been executed; 

END SUBMIT pathname 
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EXAMPLE 

This example shows a SUBMIT file that uses formal parameters and the 
command that you can enter to Invoke this SUBMIT file. The SUBMIT file, 
which resides on file :F1 :PR0GEIAM, contains the following lines: 

ATTACHDEVICE Fl AS %0 

CREATEDIR %0/%l 

UPCOPY :F1:%2 TO %0%l/%2 

The SUBMIT file contains three formal parameters, indicated by ZO, %1, 
and %2. The %0 indicates the logical name of an IRMX 86 device; the %1 
indicates the name of a directory on that device; the %2 indicates the 
name of a file which will be copied from an ISIS-II disk to the IRMX 86 
device. 

The SUBMIT command used to invoke this file is as follows: 

-SUBMIT :F1:PR0GRAM (:F1:, PROG, FILEl) 

The command sequence created and executed by SUBMIT is shown as it would 
be echoed on the console output device. 

-ATTACHDEVICE Fl AS :Fl: 

Fl, attached as :F1: 

-CREATEDIR :Fl:/PROG 
:F1:PR0G, directory created 
-UPCOPY :Fl: FILEl TO :F1 : PROG/FILE 1 
:F1: FILEl upcopied TO :F1:PR0G/FILE1 
END SUBMIT :Fl: PROGRAM 
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TIME 


This command sets the system clock. If no new time is entered, the TIME 
command causes the current system time to be displayed. 

The format is as follows: 



INPUT PARAMETERS 

hh: Hours specified as 0 through 24. 

mm: Minutes specified as 0 through 59. 

ss Seconds specified as 0 through 59. 

DESCRIPTION 

If one of the time entries in the parameter string is set, all three must 
be; there are no default settings for individual items in the parameter 
string. 

If you request the time-of-day and the system clock has not been set, the 
TIME command displays the following message: 

00 : 00:00 

See also the DATE command in this chapter if you wish to set the date in 
conjunction with the system clock. 

An Invalid time or an out-of-range entry for the TIME command causes the 
following error message to be displayed: 

illegal time 
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UPCOPY 


This conmiand copies files from a volume on ISIS-II secondary storage to a 
volume on IRMX 86 secondary storage via the iSBC 957A/B Interface and 
Execution package. 



INPUT PARAMETERS 

inpath-list List of one or more filenames of the ISIS-II files 

that are to be copied to iRMX 86 secondary 
storage, either on a one-for-one basis or 
concatenated into one or more iRMX 86 output files. 

QUERY Causes the Human Interface to pron^t for 

permission to copy each ISIS-II file to the listed 
IRMX 86 output file. Depending on which 
preposition you specify (TO, OVER, or AFTER), the 
Human Interface prompts with one of the following 
queries: 

filename, copy up TO out -pathname? 

filename, copy up OVER out -pathname? 

filename, copy up AFTER out-pathname? 

Enter one of the following (followed by a carriage 
return) in response to the query: 


Entry 

Action 



Y or y 

Copy the file. 



E or e 

Exit from the UPCOPY command. 

R or r 

Continue copying 
further query. 

files 

without 

Any other 
character 

Do not copy this 
the next file in 

file; go to 
sequence. 
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OUTPUT PARAMETERS 

TO Copies the ISIS-II file or files TO a new iRMX 86 

file or files in the listed sequence. The output 
file or files should not already exist when the TO 
preposition is used. If no preposition is 
specified, TO ;C0: is the default. If more input 
files than output files are specified in the 
command line, the remaining inputfiles will be 
appended to the end of the last listed output file. 

OVER Copies the listed ISIS-II input file or files OVER 

existing iRMX 86 destination files in the listed 
sequence. If more input files than output files 
are listed in the command line, the remaining 
input files will be appended to the end of the 
last listed output file. 

AFTER Appends the listed ISIS-II input file or files 

AFTER the end-of-data on an existing IRMX 86 
output file or files in the listed sequence. 

outpath-list One or more pathnames of the iRMX 86 destination 

files. Multiple pathnames muxt be separated by 
commas. Separating blanks are optional. If the 
preposition and output parameter defaults are used 
in the command line, the output will go to the 
iRMX 86 console screen. 


DESCRIPTION 

Before you enter an UPCOPY command on the iRMX 86 console keyboard, you 
must have your target system connected to a development system with the 
957A/B package and the package must be running. The IRMX 86 copies of 
the files will have WORLD access; that is, all iRMX 86 system users can 
peform read, write, and delete operations on the files without 
restriction. 

As each ISIS-II file in the input list is copied, the Human Interface 
will display one of the following messages on the IRMX 86 console screen, 
as appropriate: 

filename, copied up TO out-pathname 
filename, copied up OVER out-pathname 
filename, copied up AFTER out-pathname 
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CHAPTER 4. FILE HANDLING EXAMPLES 


ITils chapter shows you how to use the Human Interface file management 
commands at the user console. The primary intent is to Introduce you to 
basic file manipulation techniques by presenting a series of examples 
that illustrate typical command entries. 

Those of you who will be using the Human Interface system calls to create 
your own commands can also benefit by studying the examples. Hands-on 
experience with the file handling commands will provide you with an 
improved understanding of the interaction between the console user and 
Human Interface services during program execution. You will then have a 
better Insight as to why and how some of these same elements should be 
included in your own custom commands. 


C014MAND EXAMPLES FORMAT 


To make it easier to follow the interactive dialog between the user and 
Human Interface in the examples, the user keyboard entries are 
underscored . All other items displayed in the examples are Human 
Interface command output. For Instance, in the example: 

-copy sanp to test 

samp copied TO test 

-copy test 

aaaaa 

bbbbb 

test copied TO :C0: 


the underscored items are user command entries; all other characters and 
lines are output by the Human Interface or the supplied commands. 

Control characters, such as (CTElL/z), are enclosed in parenthesis in the 
exanples to indicate that such entries are not echoed on the console 
screen as they are entered. Do not actually enclose control key entries 
with parentheses. 


HOW TO BEGIN A CONSOLE SESSION 


You can begin an interactive dialog with the Human Interface after a 
slgn-on message is displayed on your console screen. Although the 
slgn-on message is a system configuration option, the message supplied 
with Human Interface systems is as follows: 

iRMX 86 HI Vx.x: user = WORLD 
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where the message tells you the Human Interface is running, and the 
hyphen (-) is a Human Interface prompt to indicate that it is ready to 
accept your first command line. Begin entering a command immediately 
after and on the same line as the prompt. For example: 

-copy :cl: to testl 


HOW TO CREATE A SIMPLE DATA FILE 


The COPY command is the command used to create data files during a 
console session. Assume you wish to create a file called ALPHA and write 
two lines of data into the file. Also assume you wish the data file to 
be listed under the default user’s directory configured for your system, 
which means you do not have to specify a directory name as a preceding 
component in the file’s pathname. Enter the following command and data: 

-copy :cl: to alpha 

aaaaa 

bbbbb 

(CTRL/z) 


:ci: copied TO alpha 


In this example, the :ci: in the COPY command line tells the command to 
read data from the keyboard (:ci: = console input) and write the data 
aaaaa and bbbbb to a new file named ALPHA, which will be listed under 
your system’s default user directory. You will not be prompted for the 
data lines; simply begin entering data after you press RETURN at the end 
of the command line. Your CTRL/z entry writes an end-of-file mark at the 
end of your data. 

Note that after you enter the last line of data, you MUST press the 
RETURN key before you enter a CTRL/z to insert an end-of-file. 

Otherwise, all characters entered after you press the RETURN key and 
before you enter a CTRL/z would not be written to the file. For example: 

-copy :ci: to alpha 
ccccc 

ddddd (CTRL/z) (then press RETURN) 

would only write the data ccccc to the new file named ALPHA. 

Since control characters are not echoed on the screen as you enter them, 
(such as a RETURN or CTRL function), the above file creation sequence 
would be displayed on the screen as follows: 

-copy :ci: to alpha 

ccccc 

ddddd 


:ci: copied TO alpha 
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Now, assume that when you entered the COPY command line, the Human 
Interface sent you the following message and query: 

-copy :ci: to alpha 

alpha, already exists, DELETE? 

Whenever you create a new data file, the COPY command expects a new 
pathname rather than one already listed in the directory file. If your 
entry to the query is: 

alpha, already exists, DELETE? 

the COPY command deletes the data within the existing file and waits for 
you to enter new data under that pathname. 

If your response to the query is: 

alpha, already exists, DELETE? n^ (or any other character except y) 


your COPY command is ignored and the Human Interface prompts for a new 
command entry by issuing a hyphen (-). 


HOW TO DUPLICATE FILES 


COPY command options provide a number of different ways for you to copy 
existing files. You exercise these options either by specifying one of 
the TO/OVER/ AFTER prepositions, by the way in which you specify your 
input file and output file pathname lists, or by a combination of both 
techniques. The Human Interface provides the following file copy 
services: 

• Copy files on a one-for-one basis. 

• List (display) files on the console screen. 

• Create multiple copies of the same file. 

• Copy data from multiple files to a new or existing file. 

• Replace data in one file with data from another file. 

• Add data from one or more files to the end of the data in another 
file. 

• Combine one-for-one file copying with file concatenation in a 
single COPY command. 

The examples that follow show you how to implement these various options 
and also call your attention to certain file handling considerations when 
using the COPY command. 
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HOW TO COPY TO NEW FILES 

Copying existing files to new files is most frequently done on a 
one-for-one basis; that is, you list a number of existing files to be 
copied and a matching list of files to receive the copies. The files are 
copied in the same sequence you specify in the input list and output list 
on the command line. For example, assume you wished to copy files ALPHA 
and BETA to files GAMMA and DELTA respectively. Enter the following 
command: 

-copy alpha, beta to gamma, delta 
alpha copied TO gamma 
beta copied TO delta 


There is a rule to remember about copying lists of files. Although you 
can list more input files than output files (for file concatenation, 
which is described later), you cannot successfully list more output files 
than input files in a command line because the command would not know how 
to handle the remaining output files. The COPY command will copy input 
files to listed output files until the input list is exhausted, but no 
operation will be performed for the extra output files. 


HOW TO DISPLAY FILES 

When you perform a number of file manipulations during a single session, 
it is occasionally advisable to check a file’s contents by listing it on 
the the screen before proceeding further. Assume you wish to display the 
contents of a file named ALPHA that is listed under the user default 
directory. Simply enter the command: 

-copy alpha 

aaaaa 

aaaaa 

alpha copied TO :C0: 


This COPY command exanqple used the default preposition (TO), and default 
output file (:C0:), which is the console screen. However, remember that 
one of these defaults cannot be used in a command line without using the 
other. For example, the commands: 

-copy alpha to 
8MAD, 8004: E*PARAM 


or 

-copy alpha :co; 

:C0:, unrecognized control 


obviously give poor results. 
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You can halt the scrolling of a displayed list to examine the data more 
closely. Press the following CTRL function keys to control scrolling of 
the listed output; 


CTRL/s 

Stops the data from being scrolled off the screen 
until you press a CNTRL/q or CTRL/c. 


CTRL/q 

Resumes scrolling of listed data until the end-of-file 
is reached or you enter a CTRL/c. 


CTRL/c 

Cancels listing the data and returns control to the 
Human Interface, which prompts for a new command. 


HOW TO REPLACE EXISTING FILES 

There may be occasions when you wish to update the contents of an 
existing file. The most practical way to modify a file is to create a 
new file and then replace the contents of the old file with the new 
data. Although this operation can be done by using the RENAME command, 
for now we*ll perform it by exploring the use of the COPY command’s OVER 
preposition. 

Assume the following conditions; 

You have a file named ALPHA that is accessed under that name by a 
number of different programs. ALPHA has outmoded data. 

Since you cannnot change the name without also modifying the programs 
that access ALPHA, you must retain the name but update the outmoded 
file contents. Enter the following command sequence: 

-copy :ci: to temp 
nu nu nu nu 
nu nu nu nu 
(CTRL/z) 

;cl; copied TO temp 
-copy tenqp over alpha 
temp copied OVER alpha 
-copy alpha 
nu nu nu nu 
nu nu nu nu 

alpha copied TO ;C0: 


The last COPY ALPHA command to list the file shows that the old file 
contents have been successfully replaced. We could have used the TO 
preposition in the COPY command to write TEMP over ALPHA, but since the 
Human Interface always expects a new output file when the TO preposition 
Is used, this would have caused unnecessary keystrokes as shown below; 
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-copy temp to alpha 

alpha, already exists, DELETE? ^ 

temp copied TO alpha 


Note that you now have two copies of the same new data; one in the TEMP 
file and one in the ALPHA file. If you had used the OVER preposition in 
a RENAME command instead of the COPY command, file TEMP would have been 
deleted automatically when RENAME was executed. However, if you did not 
want two existing copies of the same data, you could update the existing 
file directly from the keyboard. Enter the following command; 

-copy ;ci; over alpha 

newnewnew 

(CTRL/z) 

:ci; copied OVER alpha 


HOW TO CONCATENATE FILES 

Concatenation is the process of combining a number of files by appending 
them in sequence into a single file. You can use the COPY command in 
several ways to concatenate files: by specifying the AFTER preposition in 
the command line; by specifying more input files than output files; or by 
using a combination of both techniques. 

Assume you have four existing files named A, B, C, D respectively, and 
want to append the contents of B, C, and D to the end of file A. 

Although you could specify the TO preposition in the COPY command line, 
the TO preposition would force you to enter extra keystrokes because your 
listed output file (A) already exists. It would also force you to delete 
the previous contents of A, which is not always desirable. Therefore, 
use the AFTER preposition, as follows; 

- copy b,c,d after a 
b copied AFTER a 
c copied AFTER a 
d copied AFTER a 


Now, assume you wish to concatenate all four files into a new file called 
ALL. You can still use the AFTER preposition, or you can use the TO 
parameter, as follows; 

- copy a,b,c,d to all 
a copied TO all 
b copied AFTER all 
c copied AFTER all 
d copied AFTER all 

In this example, file A is copied to ALL and the remaining input files 
are automatically appended to the end of ALL. 
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You can save keystrokes when listing a series of files on the screen by 
using this automatic concatenation in a single command line. Assume you 
wish to list files named ALPHA, BETA, and GAMMA. Enter the following 
command, using the default TO preposition and default output file (:C0:): 

-copy alpha, beta, gamma 

aaaaa 

aaaaa 

alpha copied TO :C0: 

bbbbb 

bbbbb 

beta copied AFTER :C0: 

ggssg 

ggggg 

gamma copied AFTER ;C0: 


You can also use the OVER preposition in conjunction with file 
concatenation. For example: 

-copy alpha, beta, gamma over delta, zeta 
alpha copied OVER delta 
beta copied OVER zeta 
gamma copied AFTER zeta 


When data sequence and/or data format are Important in a concatenated 
file, remember that all copy operations are performed in the sequence you 
specify in the command line. 

Assume you have formatted data in a group of files named A, B, C, D, and 
E, and you wish to concatenate their contents into a new file named 
SQUARE in that sequence. However, if you list the input files on the 
command line in a haphazard sequence, as follows: 


-copy b,a,d,c,e to square 


the format of the total data block is destroyed, as can be seen in the 
following Incorrect and correct versions of the listed output. Although 
the data block of Latin words shown in the left-hand example seems 
correct when read horizontally, the Intent and meaning of the vertical 
columns has been lost. The right-hand example shows the corrected file 
sequence: 


b,a,d,c,e 

sequence 

A R E P 0 
S A T 0 R 
OPERA 
TENET 
ROTAS 


a,b,c,d,e 

sequence 

S A T 0 R 
A R E P 0 
TENET 
OPERA 
ROTAS 


In the right-hand example, the Latin "magic square" now reads the same 
both horizontally and vertically, which was the intended operation. 
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HOW TO DELETE FILES 


It is vital to good file housekeeping that you routinely delete obsolete 
or unused files and empty directories. (Deleting unused directories is 
described later in this chapter.) In addition to the obvious benefit of 
recovering unused secondary storage, deleting your obsolete files reduces 
confusion and file manipulation errors. 

Assume that you want to delete files ALPHA and BETA from the system. 

Enter the following command: 

"delete alpha, beta 
alpha, deleted 
beta, deleted 


Now, assume that you entered the following command line and received the 
following error message: 

-delete ay, bee, key 
ay, deleted 
bee, deleted 
key, does not exist 


The error message for the KEY file tells you one of three things: 

1. There is a syntax error in the spelling of the KEY file. 

2. The file does not exist. 

3. The file exists in a directory other than the one you are 
currently accessing (see the directory examples later in this 
chapter). 


HOW TO USE DIRECTORIES 

A user directory is simply another kind of file under which you assign 
and maintain other files or directories. A directory file is 
distinguished from a data file or program file by a directory heading 
that is automatically created when you create a new directory. Under 
that heading, the directory maintains a formatted list of files and other 
directories that you subsequently assign to it. Directories provide you 
with a convenient and efficient technique for organizing large numbers of 
files into logical groupings. Creating your own user directories will 
aid you in two ways: 

1. It*s easier to keep track of individual files when you*re 
maintaining large numbers of files on the system. 

2. It reduces the possibility of accidental destruction of files, 
either by yourself or other system users. 
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A directory contains a list of all files assigned under its name, which 
you can display by using the DIR command (described later). Optional DIR 
command parameters also allow you to access and display other pertinant 
information about each file, such as file size and other file attributes. 

Previous command examples in this chapter have used the default user 
directory configured for your system to create and access files. The 
following examples show you how to create and use your own directories 
for easier file management. 


HOW TO CREATE A NEW DIRECTORY 

Whenever you wish to group a series of files under a single topical 
structure, you normally create a new directory in which to assign them 
before the files themselves are created. (You can also move existing 
files under a new directory name by using the RENAME command, as 
described later. ) 

You create new directories by using the CREATEDIR command to specify a 
list of directory names for the new directories. You will find it easier 
to keep track of both your directories and files if you use directory 
names that have lexical meaning; that is, the names give some hint of a 
directory’s topical structure. 

Assume you wish to create two directories named MYTEST and NUTEST under 
which you will assign several practice files. Enter the following 
command: 

-createdlr MYTEST, NUTEST 
MYTEST, directory created 
NUTEST, directory created 


You probably noticed that we entered the directory pathnames in capital 
letters in the above example. It is suggested that you also capitalize 
all directory pathname entries in a CREATEDIR command when you create new 
directories, and use lowercase characters for data pathnames when you 
create new files with the COPY command. This practice is recommended 
because, when you subsequently list a directory by using the DIR command 
(described later), it will be much easier for you to distinguish between 
file pathnames and directory pathnames. 

Once the directories or files are created, you can enter their pathnames 
in either lowercase or uppercase characters in subsequent commands; the 
Human Interface commands make no distinction in interpretation. 
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HOW TO REFERENCE A DIRECTORY 

After you create a new directory, all named files or directories that you 
assign to that directory will have a hierarchical relationship to this 
"parent" directory. This relationship to the parent is called a path . When 
you wish to access any file or other directory assigned to the parent, you 
must specifically identify the path in the form of a pathname in your 
command. 

For exaiT 5 )le, assume you have a directory named NUTEST under which you have 
another directory named SAMP. SAMP, in turn, has a data file named TEST. 
NUTEST is then the parent directory for the SAMP directory and SAMP, in 
turn, is the parent for the TEST data file. In a command, the pathname for 
the SAMP directory would be NUTEST/SAMP, where the slash characters (without 
embedded blanks) separate the individual hierarchical components of the 
pathname. The pathname for the TEST data file would be NUTEST/SAMP/TEST. 


HOW TO ADD NEW ENTRIES TO A DIRECTORY 

Previous data file examples in this chapter used the default user directory 
(as configured for your system) for all file creation and access. 
Consequently, each time we created a new file or accessed an existing one, 
we only needed to enter the filename for the file; the directory name as the 
first component of a file's pathname did not have to be specified in a 
command. However, whenever you wish to create a new data file to be 
assigned to a specific directory , you must precede the filename by the 
directory name and separate the two names with a slash (/) in the COPY 
command, as described in the previous subsection. 

For example, assume you wish to create files named SAMPl and SAMP2 and 
assign them to the MYTEST directory. Enter the following commands: 

-copy :ci: to mytest/sampl 

aaaaa 

(CTRL/z ) 


:ci: copied TO mytest/sampl 
-copy :ci: to mytest/samp2 
bbbbb 
(CTRL/z) 


:ci: copied TO my test /samp 2 


Remember that once you have added files to a specific directory, every 
subsequent operation Involving those files must specify a preceding 
directory name and the slash separator. For example, assume you wanted to 
delete files SAMPl and SAMP2 from the MYTEST directory and entered the 
following command: 

-delete mytest/sampl, samp2 
mytest/sampl, deleted 
samp2, does not exist 
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The Human Interface issued the “does not exist" message for SAMP2 because 
it looked for the file in the default user directory instead of the MYTEST 
directory. The correct command line entry should have been: 

-delete mytest/sampl,mytest/samp2 

so that the Human Interface would search the correct directory for each 
listed file. 


HOW TO CREATE A DIRECTORY WITHIN A DIRECTORY 

No doubt you have already realized that since you can create new 
directories within the default user directory, you can also create other 
directories within a given path of directory names in an ever-descending 
hierarchy. This process exactly duplicates the classification of topics 
and subtopics within a standard office filing systeip. 

For example, assume you have data files ALPHA, BETA, and GAMMA assigned to 
the MYTEST directory and now wish to add a new directory file named URTEST 
to the directory. Enter a CREATEDIR command, as follows: 

-createdir ray test /URTEST 
my test/URTEST, directory created 


Now, assume you wish to create a new data file named NOMOR and assign it to 
the URTEST directory. Enter the following COPY command: 

-copy :ci: to mytest/urtest/nomor 

nononon 

nononon 

(CONTROL/z ) 

:cl: copied TO mytest/urtest/nomor 


The "MYTEST/URTEST" sequence is the pathname for the URTEST directory, and 
the "MYTEST/URTEST/NOMOR" sequence is the pathname for the NOMOR Jfile. The 
entire pathname must be specified for directories or files in any 
subsequent file handling. For example, assume you have another data file 
in URTEST named SUMOR and wish to list both NOMOR and SUMOR on the console 
screen. Enter the following command and specify the pathname for each file 

-copy mytest/urtest/nomor,mytest/urtest/sumor 

nononon 

nononon 

ray test/urtest/nomor copied TO :C0: 
sums urns urn 
sums urns urn 

my test/urtest/sumor copied TO :C0: 
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You can also specify file operations involving two or more different 
directories, and these directories need not be on the same path. Assume 
you wish to list the ALPHA file from MYEST and a file named DIFF on a 
directory path ONE/MOR. Enter the following command: 

-copy ny test/alpha, one/mor/diff 

aaaaa 

aaaaa 

my test/alpha copied TO :C0: 

yyyyy 

yyyyy 

one/more/diff copied TO ;C0: 


HOW TO LIST DIRECTORIES 


Previous exanqples have shown you how to list data files by specifying a 
directory pathname in a COPY command. However, you should not use the COPY 
command because COPY will list the directory as though it were a data 
file. For example, if we used the COPY command to list the MYTEST 
directory on the screen: 


-copy mytest 

alphabetagammaurtest copied to ;C0: 


the resulting output is almost unreadable. Instead, use the DIR command to 
list the directory’s catalog of data files and/or directories as follows: 

-dir mytest 

01 JAN 78 00:00:00 

DIRECTORY OF MYTEST ON VOLUME disk2 
alpha beta 

gamma URTEST 


In this exan^le, you used the DIR command's default TO preposition and FAST 
format for the listing. You could have sent the directory listing to 
another output file and specif ed either the OVER preposition to write the 
listing over the file's previous contents, or the AFTER preposition to 
append the directory listing to other data. If you want to list more 
information about each file, specify the EXTENDED parameter. See the DIR 
description in Chapter 3 for exaII^>les of the available listing formats. 
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HOW TO MOVE FILES BETWEEN DIRECTORIES 

There may be situations when you wish to reorganize a large group of 
existing flies under new headings (directories). You can move files from 
one directory to another by using the RENAME command. For example, assume 
you wish to move files ALPHA, BETA, and GAMMA from the users default 
directory to the existing directory MYTEST, and file DELTA from the user 
default directory to an existing directory named NUTEST. Enter the 
following command line, using the QUERY parameter (optional): 

-rename alpha, bet a, gamma, delta to MYTEST/alpha,MYTEST/beta, & 
MYTEST/ga^,NUTEST/deltr query 
alpha, RENAME TO MYTEST/alpha? 2 . 
alpha renamed to MYTEST/alpha 
beta, RENAME TO MYTEST/beta? 
beta renamed to MYTEST/beta 
gamma, RENAME TO MYTEST/gamma? ^ 
gamma renamed to MYTEST/gamma 
delta, RENAME TO NUTEST/delta? ^ 
delta renamed to NUTEST/delta 


Assume you later decided to move file ALPHA back to the default user 
directory. You need not specify the default directory In the new pathname 
for ALPHA. Enter the following command: 

rename mytest /alpha to alpha 
mytest /alpha RENAMED to alpha 


Any subsequent operations Involving file ALPHA would only require the 
filename. For example: 

-copy alpha 

aaaaa 

aaaaa 

alpha copied TO :C0: 


HOW TO DELETE A DIRECTORY 

You delete unused directories from secondary storage by using the DELETE 
command. However, the Human Interface protects you from accidently 
destroying valuable files by refusing to delete a directory that contains 
one or more files. For example, assume you wished to delete directory 
MYTEST and did not realize It contained a data file named ALPHA and a 
directory named DED that Itself contained a data file named LIV. You 
entered the following command: 

-delete nytest 

mytest, directory not entity 
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It would probably pay to list the MYTEST directory by using the DIR 
command at this point. You now have several options: use the RENAME 

command to move any files to to be saved to a different directory on the 
same volume, or use the DELETE command to delete the entire contents of 
MYTEST before deleting the directory. 

Assume you wish to move ALPHA to the NUTEST directory and delete the rest 
of the directory’s contents so that MYTEST itself can be deleted. Enter 
the following commands: 

-rename my test /alpha to nutest /alpha 
mytest/alpha renamed to nutest/alpha 
- delete mytest/ded/liv,mytest/ded,mytest 
my test/ded/liv deleted 
mytest/ded deleted 
mytest deleted 


The RENAME command automatically deleted the MYTEST/ALPHA pathname from 
the MYTEST directory. Note how the pathname sequence in the DELETE 
command travelled upward through the hierarchical structure to the MYTEST 
directory as the last item to be deleted. 


HOW TO RENAME FILES AND DIRECTORIES 


The most direct method to save the contents of a file or directory but 
change its pathname is to use the the RENAME command. To make the 
process easier to follow, renaming of files and directories will be 
described separately. 


HOW TO RENAME FILES 

Assume you wish to change the name of file ALPHA to a new name of OMEGA, 
where OMEGA does not already exist. Enter the following command: 

-rename alpha to omega 
alpha renamed to omega 


The ALPHA pathname would be automatically deleted from the system when 
the RENAME command was executed. You can also rename lists of files to 
new pathnames, and in this case, it is useful to include the QUERY 
parameter in your command line to make certain that your old pathnames 
and new pathnames are matched up in the way you intended. 

Assume you wish to rename files ALPHA, BETA, and GAMMA to TOM, DICK, and 
HARRY respectively. Enter the following command sequence: 

- rename alpha, beta, gamma to tom, dick, harry 
alpha renamed TO tom 
beta renamed TO dick 
gamma renamed TO harry 
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Remember that when using the RENAME command, you must always have a 
one-for-one match of pathnames between the new list and the old file list. 
For example, more old pathnames than new pathnames would cause the 
following exchange at the console: 

~rename alpha, beta to tom 
alpha renamed to tom 
un -matched path name lists. 


Similarly, specifying fewer old pathnames than new names would cause the 
following exchange: 

-rename alpha to beta, tom 
alpha renamed to beta 


So far, these RENAME examples have used the TO parameter to give new names 
to existing files. However, you can also use the OVER preposition with 
RENAME. The primary purpose of OVER is to move data from one named file 
over the data in another existing file. This matches the action of the 
OVER preposition in the COPY command with one important distinction: 

RENAME automatically deletes the input data file from the system when the 
command is executed. 

Exercise a little care here! It^s easy to get into semantic confusion when 
using the OVER preposition in a RENAME command. Just remember a few simple 
rules: 

« Use the pathname of the data to be moved to a different but existing 
pathname as the input parameter; that is, on the left-hand side of the 
OVER preposition. This pathname will be deleted from the system when 
the command is executed. 

® Use the pathname that receives the input data as the ouput parameter; 
that is, on the right-hand side of the OVER preposition. The previous 
contents of this file will be replaced when the command is executed. 

For example, assume you have a file named ABLE whose contents consist of 
the data line aaaaa, and another file named BAKER whose contents consist of 
the data line bbbbb. You wish to rename ABLE with the name BAKER. Enter 
the following command: 

-rename able over baker 
able renamed OVER baker 


Now, let’s see what happened to the contents of the file previously named 
ABLE but now named BAKER: 

-copy baker 
aaaaa 

baker copied TO :C0: 
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The previous contents of BAKER have been deleted from the system, and 
pathname ABLE has been deleted from its directory .You can also use the TO 
preposition to rename files with other existing pathnames. Using TO 
might be slightly less confusing but you must enter extra keystrokes. 

For example, assume you wish to rename ALPHA and BETA with the existing 
file names GAMMA and DELTA. Enter the following command: 

-rename alpha, beta to gamma, delta 
gamma, already exists, DELETE? ^ 
alpha renamed TO gamma 
delta, already exists, DELETE? 
beta renamed TO DELTA 


HOW TO RENAME DIRECTORIES 

A directory can be renamed to new pathname on the same volume (but not to 
an existing pathname). Assume you have a directory whose pathname is 
ALPHA/BETA and wish to rename it with a new pathanme of AY/BEE. Enter 
the following command: 

-rename alpha/beta to AY/BEE 
alpha/beta renamed TO AY/BEE 
-dir alpha/beta 
alpha/beta, does not exist 


Be cautious about renaming directories! That last message tells you the 
consequences of renaming a directory to a new pathname. Once you rename 
a directory, all files listed under that directory will also have their 
pathnames changed. If your system has other programs that use data files 
that are listed under the old directory name, those programs will never 
find the files. In such a case, either the directories would have to be 
renamed to their original names or the programs would have to modified. 

In summary, the distinctions between using the RENAME and COPY commands 
are as follows: 

• When you use COPY to move the contents of an existing file TO a 
new file or OVER an existing file, the input file still exists. 

• When you use RENAME to move the contents of an input file TO a 
named new file or OVER an existing file, the input pathname is 
automatically released for new uses. 


HOW TO MOVE FILES ACROSS VOLUME BOUNDARIES 


You can use all Human Interface file handling commands except RENAME to 
manipulate files across volume boundaries. That is you can copy files or 
directories from one diskette or disk platter to another one mounted in a 
different drive. The restriction against using RENAME across volume 
boundaries is intended for the protection of files against accidental 
deletion. 
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You access a different volume by entering the logical device name (for 
the drive on which the volume is mounted) as the first item in the 
pathname. For example, assume you have a volume mounted on a drive whose 
logical name is :fl:. Further assume you wish to list the root directory 
for that volume to see what directories and data files you have on the 
volume. Enter the following command: 

-dir :fl : 

01 JAN 81 00:00:00 

DIRECTORY OF :fl: ON VOLUME dlsk2 

able baker chuck OMNI samp 

BUS nusamp STATS 


Assume you wish to copy file ABLE from this volume mounted on :fl: to the 
MYTEST directory on your system’s default volume (:f0:). Enter the 
following command: 

-copy :fl:/able to mytest/able 
:fl :/able copied' TO my tVst/abie 


If you then wish to delete files ABLE and (for instance) BAKER from the 
:fl: volume, simply enter the command: 

-delete :fl : /able, :fl: /baker 
:fl:/able, deleted 
:fl: /baker, deleted 


Now, assume the following conditions: 

• You have two data files on the :fl: volume with the pathnames 
STATS/SALES/FEB and STATS/SALES/MAR. 

• You wish to merge both files to a new file with the pathname 
MY TEST/PEEK/ SUB TOT on your system’s default volume. 

Enter the following command: 

-copy :fl : /stats/sales/feb, :fl : /stats/sales to nytest/peek/subtot 
:f 1: /stats/sales/f eb copied TO mytest/peek/subtot 
:f 1: /stats/sales/mar copied AFTER nytest/peek/subtot 


Note that a volume prefix must be specified for each pathname in any 
command that crosses volume boundaries. A volume uses the prefix of the 
drive on which it is mounted. 
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HOW TO FORMAT A NEW VOLUME 


Whenever you wish to create a new volume on a secondary storage device 
(such a diskette, disk platter, or bubble memory), you must format the 
volume before you can write any information in it. Assume you are going 
to mount a new diskette on a disk drive with the prefix ;fl:. Further 
assume you are going to name the volume NEWVOL to meet the Human 
Interface requirement for a six-character volume name. 

Enter the following command: 

-format :fl:NEWVQL 

volume (NEWVOL) will be formatted as a NAMED volume 
granularity = 128 
interleave =5 
numberf nodes =50 
volume formatted 


This formatting exari 5 )le exercised all the default options. Only a 
six-character volume name is a required parameter. Since all your 
accesses to the volume will be through the logical name for the drive on 
which the volume is mounted, the question naturally arises as to why a 
volume name is required. There are two reasons: 

1. The Human Interface requires a volume name for its own internal 
processing of your read/write accesses to the volume. Once the 
volume is formatted, you need never specify the volume name in a 
command; you only specify the logical name for the device on 
which you later mount the diskette. 

2. For diskettes, a volume name gives you a method for Identifying 
a volume in case the stick-on label on the diskette gets lost or 
destroyed. You need only mount the disk on a drive and enter a 
DIR command for that drive to get a directory listing that 
specifies the volume name. 

The GRANULARITY, INTERLEAVE and FNODES parameters tell the FORMAT command 
how you want the physical space (for instance, disk surface space) on the 
volume allocated and accessed for maximum efficiency. The default 
parameters caused the NEWVOL example to be formatted with the following 
attributes: 

• The default NAMED parameter specifies that you will be using the 
volume only to handle named files and directories. If you 
specified the PHYSICAL parameter, the entire volume would be 
treated as a single, large physical file. Once you you define 
the volume as NAMED or PHYSICAL, you can only use it for that 
purpose. 

• The GRANULARITY parameter specifies the minimum number of bytes 
to be allocated for each increment of file size on the volume. 

The default granularity is the granularity of the physical 
device. Once the volume granularity is defined, it is applied to 
every file you create on the volume. 


4-18 



FILE HANDLING EXAMPLES 


For example, assume the default volume granularity for your device is 
1024 bytes. Each time you create a new file on the volume, the I/O 
System will automatically allocate 1024 bytes of primary storage to 
that file, whether or not the file requires the full 1024 bytes. If 
the size of your file exceeds 1024 bytes, the I/O System will increment 
your file size by still another block of 1024 bytes, and so on, until 
the end~of-file is reached. 

• The INTERLEAVE default specifies that you want an interleave factor 
of 5. The interleave factor maximizes access speed for the files on 
a given volume, depending upon the intent of the volume and the 
device configuration of your system. 

For example, an interleave value of 5 for a flexible disk system 
means that, for each file, the I/O System will read every fifth 
sector on the diskette, starting from an index of 1 (other, hard 
disk systems may be different, depending on your hardware 
configuration). Therefore, the I/O System does not need to wait for 
the disk to make a complete revolution before it accesses the next 
sector; the next sector by an increment of 5 is ready to be accessed 
for read /write by the time the first accessed sector has been 
processed. 

Note that the INTERLEAVE is the only optional parameter that is 
meaningful for volumes formatted for PHYSICAL files; the FNODES and 
GRANULARITY options are ignored in FORMAT commands that specify a 
PHYSICAL file format for the volume. 

• The default FNODES parameter specifies that you wish create a 
maximum of 50 files on the volume, including directory files. 
Although the actual number of fnodes you can specify is 7 through 
32,767, at a practical level one of your determining factors will be 
the incremental file size you specify in the GRANULARITY parameter. 


DISKETTE SWITCHING PROCEDURES 


If your system is configured with the iSBC 204 flexible disk controller and 
you are using single-density diskettes to perform file management 
functions, a special procedure is required to switch the diskettes. 

Perform the following steps: 

1. Remove the old diskette and mount the new one into the drive. 

2. Enter a DIR command for the root directory of the new diskette to 
force physical access. The root directory "name” will actually be 
the prefix (logical device name) for the drive on which the diskette 
is mounted. For example: 

-dir :fl: 

The following exception message will be displayed: 

E$I0 
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3. Ignore the error message and begin entering Human Interface 

commands that access the volume. If your system is configured 
with a dual-density disk controller, use the diskette changing 
procedures described in the iRMX 86 INSTALLATION GUIDE. 


HOW TO USE A SUBMIT FILE 

A submit file gives you the ability to load and execute an entire series 
of commands by entering a single SUBMIT command. Whenever you have a 
group of commands that you must execute in sequence and on a routine 
basis, using a submit file will save you time, keystrokes, and keyboard 
entry errors. 

Before you create a submit file, however, you should be aware of two 
restictions about the commands that are loaded and executed from such a 
file: 

1. There is no way to change parameters in any given command between 
submit file executions. If you wish to change any parameter 
specification in a command line, you must recreate the entire 
submit file. 

2. You cannot change the execution sequence for commands without 
recreating the file. 

Now, assume you have three user-created application programs whose 
command names are the pathnames :F1: /STATS/PASSl, ;F1: /STATS/PASS2, and 
:F1: /StATS/PASS3 respectively. The pathnames tell you that the volume in 
which they are located is mounted on the drive with the logical name 
:F1:, all three programs are located in the STATS directory, and the 
program names are PASSl, PASS2, and PASS3. 

• PASSl reads data from an update file whose pathname is always 

: FI: /NEWDATA, processes it, and writes it over an existing output 
file whose name is always :F1: /FETCH. 

• PASS2 reads data from :F1: /FETCH, processes it, and writes the 
output after the end of data on an existing file named :Fl: /CARRY. 

• PASS3 reads the data from :F1: /CARRY, processes it, and writes 
the output over an existing file whose pathname is :F1: /TOTAL 

• The Human Interface COPY command reads : FI: /TOTAL and writes it 
to the :C0: device (console screen). You could have PASS3 write 
directly to :C0: but you would then have no way to recopy the 
file. 

Assume you have created your submit file with the pathname MYTEST/GETIT 
and you now wish to create the NEWDATA file from :cl: and execute the 
submit file. Enter the following commands: 
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-copy ;cl; to ;fl:/newdata 

aaaaaa 

bbbbbb 

cccccc 

(CTRL/z) 

-SUBMIT mytest/getit 

The Human Interface will read the list of commands from the GETIT file as 
though you were entering them from the keyboard, follow the pathnames to 
the stored programs, load, and execute each program in sequence* 
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The Human Interface system calls provide a convenient and consistent 
method for handling parameter parsing and processing in user-designed 
commands. You implement parameter processing by using appropriate system 
calls when you write the application program. 

After you have assembled or compiled, linked, and then stored your new 
command as an object module in secondary storage, a console operator can 
load the program file by typing its command name (pathname of the program 
file), plus any desired or required parameters on the console keyboard. 


GENERAL COMMAND LINE STRUCTURE 


The general structure for a command line is as follows: 

command-name lnput“pathname-list [preposition 
out put -pathname -lis t ] [other parameters] 
c ommand-e nt ry- t e rmi na t o r 

The console operator must always specifically type the "command name" 
entry on the keyboard to load and execute the associated program file. 
Except for the "command entry terminator" (RETURN, LINE FEED, or ESC 
key), all other command elements are optional, and the console operator 
may use default options when the command line is entered. 

Before you create a new command, you must make a number of decisions that 
will affect the command line structure: 

• The Intended function or functions of the command. 

• A command name, which you will use as the pathname for the 
executable program file. Ideally, the command name should be a 
descriptive verb or ndun that has some functional meaning for the 
console operator who will be executing the command. COPY and 
TIME are examples of command names that are a descriptive verb 
and a descriptive noun, respectively. 

• For file handling commands, an input pathname-list is usually 
desirable. You will use the C$GET$INPUT$PATHNAME call to parse 
the input pathname-list. 

• If output is to be performed, you will use the 
C$GET$OUTPUT$PATHNAME call in your program to parse the 
preposition and output pathname-list. 

• If other parameters are to be used in the new command, use the 
C$GET$PARA^ffiTER call to parse the parameters. 
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Comaands are programs that can contain system calls, including those 
supplied by the Human Interface* The Human Interface system calls are 
divided into functional groups, as follows: 

• Input and output parameter calls 

• Message processing calls 

• Command processing calls 

• Program control call 

• Parameter parsing calls 

A brief description of the functions performed within these groups is 
provided in the following subheadings; more specific information is given 
in the individual call descriptions in Chapter 6. 


INPUT AND OUTPUT PARAMETER CALLS 


Every Human Interface command (Intel-supplied or user-created) that 
performs I/O as part of its processing, must contain two or more of the 
following elements in its parameter string: 

• Command name 

• Input list of pathnames 

• Preposition (TO/OVER/AFTER entry) and output list of pathnames. 
Exanq>les: 

command name in-pathname -list preposition output destination 

COPY a,b TO c,db 

RENAME alpha, beta OVER gamma, delta 

The command name is usually a descriptive verb, and is a required element 
for every command. When any form of I/O is to be be performed, a list of 
one or more input files must be specified. When output is to be 
performed, both a preposition and a list of one or more destination files 
must be specified to receive the output. 

The Human Interface provides four system calls that you can use to 
process the I/O elements in a command line: 

C $GET$ I NPUT$PATHNAME 

Returns a pathname or pathnames that Identify the input source or 
sources. 
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C$GET$OUTPUT$PATHNAME Returns a pathname or pathnames that 

identify the destination or destinations of 
the output. If the operator does not 
specify a preposition and pathname in a 
command line, TO :C0: (console output) is 
the default. 


C$GET$INPUT$CONNECTION Returns an Extended I/O System input 

connection to a file specified by a pathname 

C$GET$OUTPUT$CONNECTION Returns an Extended I/O System output 

connection to a file specified by a pathname 


These calls are basic to I/O processing and provide a consistent 
interpretation for commands. They also provide you with a method of 
setting up the input and output connections for a command line. 

Although you can use GET$INPUT$PATHNAME without using 

GET$OUTPUT$PATHNAME , the reverse is not true. In your source statements, 
a call to GET$INPUT$PATHNAME must always precede a call to 
GET$OUTPUT$PATHNAME for pathname parameters. 

For example, assume you have written a program whose command name is 
REFINE. If the console operator enters the command line: 

REFINE ALPHA TO BETA 

your program calls C$GET$INPUT$PATHNAME to get the pathname ALPHA. 
C$GET$INPUT$CONNECTION is then called to get a connection to the ALPHA 
file. After getting the connection, REFINE performs its programmed 
operation and then calls C$QET$OUTPUT$PATHNAME to get the BETA output 
pathname. The program then calls C$GET$OUTPUT$CONNECTION to get a 
connection to the BETA file. Finally, REFINE writes the data to the 
output file. 

Invoked programs have two "standard logical devices" available: a 
Standard Input and a Standard Output. You can establish and manipulate 
these logical devices by calling the system calls that parse the command 
line and establish the standard I/O connections. 

The Standard Input is parsed by the C$GET$INPUT$PATHNAME system call from 
the input pathnames that appear after the command name on the command 
line. The pathnames returned by G$GET$INPUT$PATHNAME may be given to the 
C$GET$INPUT$CONNECTION routine to create an I/O connection. If the 
C$GET$INPUT$CONNECTION call finds the input file does not exist, the 
following message is issued to the user's console: 

pathname, does not exist 

The Standard Output is parsed by using the C$GET$OUTPUT$PATHNAME call in 
your program. The call to this routine should appear immediately after 
call to C$GET$INPUT$PATHNAME. User output redirection is 
achieved by using the TO, OVER, or AFTER prepositions, which must appear 
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immediately after the Standard Input specification on a command line. 
These prepositions are interpreted by the C$GET$OUTPUT$PATHNAME and 
C$GET$OUTPUT$CONNECTION routines called in your program. When accepted 
by a command, these prepositions are reserved words that appear in a 
command line with the following syntax: 

TO 

OVER outpath“list 

AFTER 

If a TO/OVER/AFTER preposition is not found on the command line, the 
default supplied by the C$GET$OUPUT$ PATHNAME call will be used. 

The pathname parameter may be either for a single file or a list of 
files. The TO/OVER/AFTER prepositions give the user a choice in the way 
a specified pathname is to be handled. 

The TO preposition specified in a command line indicates that the 
pathname should not already exist as a maintained file before the 
operation is performed. If the parsing call finds the file does exist, 
the following message is displayed on the console screen: 

pathname, already exists, DELETE? 

Only a keyboard response of "Y" or "y" will cause the operation to be 
performed for that particular pathname in a pathname list. 

The OVER preposition in a command line specifies that, if the pathname 
already exists, the pathname is to deleted and command execution is to 
continue. 

The AFTER preposition in a command line specifies that the standard 
output is to be appended to end of the contents of the pathname. 

The Command line Interpreter (see the description in Chapter 1) provides 
protection for a user’s files for every preposition except OVER. For 
exanqp le: 

TO xz 
OVER xz 
AFTER xz 

all execute without a warning message if xz does not exist. However, 
only the OVER preposition can replace an existing file without the 
warning message being Issued (although AFTER can concatenate to an 
existing file). 


MESSAGE PROCESSING CALLS 

The message processing calls provide a means to send and receive messages 
from the user’s console, and to format a default message for a specified 
exception code. 
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COfMAND PROCESSING CALLS 


The command processing calls are Intended for users who wish to create 
their own stream of commands or employ modifications to some of the 
functions performed by other Human Interface calls. There are three such 
calls and they are used in combination, as follows: 

1. C$CREATE$COMMAND$CONNECTION — establishes a token for a command 
connection that allows multiple line commands without 
interference from other tasks. The command connection TOKEN 
established by the call is used in the C$SEND$COMMAND and 
C$DELETE$COMMAND$CONNECTION calls. 

2. C$SEND$COMMAND — accepts command lines and combines them with 
lines previously sent. After a full command is received, 
C$SEND$COMMAND loads the command for execution. 

3. C$DELETE$COMMAND$CONNECTrON — deletes a command connection TOKEN 
previously established by a C$CREATE$COMMAND$CONNECTION call and 
frees the memory used for the connection's data structures. 


PROGRAM CONTROL CALL 


The C$SET$CONTROL$C call lets you modify the "standard" response of the 
CTRL/c function by changing the calling program's CTRL/c semaphore to 
some other semaphore specified in a SET$CONTROL$C call. An application 
example would be to change the CTRL/c semaphore of an edit program so 
that when CTRL/c was pressed, it would not cause the editor to exit but 
would instead allow it to cancel the current operation and pronq)! for a 
new command. 


parameter parsing calls 


The Human Interface parsing calls help ensure system consistency in 
processing commands. The parsing calls minimize parsing inconsistencies 
in user-created programs, thus making it easier for the programmei;* to 
provide command line parsing in the new program. The parameter parsing 
calls support two different types of parameters: 

• The first type of parameter are parameters with values, which are 
keyword parameters and preposition parameters. Parameters with 
values may appear in three different forms: 

keyword=value-part (keyword parameter) 

keyword (value-part) (keyword parameter) 

keyword value-part (preposition parameter) 

Note that the first two forms are called keyword parameters and the last 
form is called a preposition parameter, and that all three have a keyword 
and a value-part. The differences between the forms are the separators 
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used in each. The reason for distinguishing between keyword parameters 
and a preposition parameter lies in the method used to recognize them 
during command line parsing: 

• The presence of the equal sign (*) or the pair of parentheses () 
lets the Command Line Interpreter recognize keyword parameters 
without foreknowledge of the keywords. 

• The structure of the preposition parameter is so loose that the 
Command Line Interpreter must be provided with a list of the 
prepositions before they can be recognized. You must supply the 
CLI with this list in the form of a predict $t able whenever a 
parameter is requested from the parsing routines. See Table 6-1 
for a listing of the Human Interface parameter parsing calls. 

The value-part of a parameter is either a single value or a list of 
values separated by commas. In addition, the value-part may itself 
contain value-lists. If enclosed in parentheses, a value -list will be 
returned to the STRING$TABLE as one value, including the parentheses. 

For exanqple: 

A,(B,C,D),E 

where (B,C,D) will be returned as one value. The string$table format is 
illustrated in Appendix C this manual. 

• The second type of supported parameter are lists of values, which 
may consist of a single value or a list of values that comprise 
the value-part of a parameter. The values must be separated by 
coimnas. Note that since a value-list is considered one value, 
any quote marks appearing within the parentheses will not get 
deleted. See the C$GET&PARAMETER system call in Chapter 6 for 
more Information. 

Parameter parsing may be performed by using high-level calls to get 
parameters or characters. If, Instead, a command line is accessed at the 
character level, it is the program’s responsibility to provide syntax 
compatibility. Application programs will not receive any comments found 
in the command lines. 

All or a portion of a parameter can be quoted by using either single or 
double quote marks. The same type of quote mark must be used to end a 
quoted string as was used to begin the string; that is, if a quoted 
string began with a single quote( * ) it must be terminated with a single 
quote. 


PARAMETER SYNTAX CONSIDERATIONS 

Preposition parameters, such as TO/OVER/AFTER, may not be abbreviated. 
However, keyword parameter names may be abbreviated in one of two ways: 

1. Standard Abbreviation - this is performed by typing only as many 
characters of the parameter as are necessary to make it unique. 
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2. Syllabic Abbreviation - this is performed by conforming to the 

following rules: 

a. If a name consists of two or more concatenated words, use 
the first letter from each word. Digit sequences may not be 
abbreviated. 

b. If a name consists of only one syllable, use the first two 
letters of the parameter name. 

c. If a name consists of two or more syllables, use the first 
letter of the first two syllables. 

d. If negation is used (i.e., NOLIST), the "NO” is not 
abbreviated; for exanq>le, NOLI. 

e. If rules a through c result in the same abbreviation for 
different name elements, a third letter must be added to one 
of the names to achieve uniqueness in the abbreviation. 
However, the third letter need not be added if the 
conflicting names appear in different programs, or in the 
same program but in different contexts. 


COMMAND INVOCATION 

All executable programs are non-resident and are invoked as separate 
iRMX 86 programs. After the command name has been broken out of a 
command line, the CLI parses for the command pathname. If the pathname 
contains an explicit logical name, the pathname is used "as is". 

However, if the pathname consists only of components, such as a single 
filename, the CLI first searches the User Program directory (;PROG:), 
where user-created commands are cataloged. If the file is not found, the 
CLI then searches the System Command directory (: SYSTEM:), where the 
Human Interface commands are cataloged. Note that this order of search 
and the presence of the directories are configuration-time options. See 
Table 5-1 and Chapter 1 for descriptions of the :PROG: and : SYSTEM: 
directories. 


PROGRAM CONTROL 

When a user invokes a Human Interface command, the Human Interface 
invokes the Application Loader to load the command from secondary storage 
and create it as an I/O job. Whenever the calling task’s priority is the 
highest, the command starts executing. While the command is executing, 
terminal is ignored and the user cannot enter other commands until the 
first command finishes processing. In order to finish processing, the 
command must contain, as its last executable statement, a call to 
EXIT$IO$JOB. Otherwise the terminal will be hung up forever. 

The format of the call to EXIT$IO$JOB is as follows: 

CALL RQ$EXIT$I 0$ JOB (0,0, excep $pt r ) 
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This Implies a normal exit with no message sent to the message mailbox 
and with the exception code returned in the location pointed to by 
excep$ptr. 

If an executing program contains a C$SET$CONTROL$C system call, an 
operator can cancel program execution by pressing the CTRL/c key. See 
the C$SET$CONTROL$C system call description in Chapter 6. 


EXCEPTION HANDLER 

Exceptions are divided into two categories: programming errors and 
environmental conditions. Programming errors occur when the iRMX 86 
system detects a condition that normally can be avoided by correct 
coding. Environmental conditions, in contrast, are generally outside the 
control of the application program. 

The Human Interface provides a default exception handler for each program 
it creates. This exception handler receives control on the occurrence of 
all exceptions. You can cause all exceptions or no exceptions in an 
application to be passed to the exception handler by using the Nucleus 
C$GET$EXCEPTION$HANDLER and C$SET$EXCEPTION$HANDLER system calls. The 
action taken by Human Interface exception handler will be to print and 
error message and then cancel the program. 

Since you may not want to construct a special exception message in a user 
application, you can use the Human Interface C$FORMAT$EXCEPTION system 
call to construct a standard message. You can pass either programming or 
environmental exceptions to C$FORMAT$EXCEPTION, which will construct a 
standard message. The application program would issue the message and 
then either continue execution or exit itself. 


LOGICAL NAMES 


You may use either the logical names provided by the Human Interface or 
create your own at system configuration time. See the iRMX 86 
CONFIGURATION GUIDE for more information. The standard logical names and 
their meaning are described in Table 2-1. 

You can also assign logical names to new physical devices that are added 
to the system without going through a system reconfiguration. See the 
ATTACHDEVICE command in Chapter 3 for more information. 


LOAD MODULE FORMATS 


You can create new application programs in either relocatable or absolute 
load format. However, if you use an absolute format, you must reserve 
memory for the absolute object modules at iRMX 86 system configuration 
time. Refer either to the iAPX 86,88 FAMILY UTIILITIES USER’S GUIDE 
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for 8086-BASED DEVELOPMENT SYSTEMS or to the 8086 FAMILY UTILITIES GUIDE 
for 8080/8085-BASED DEVELOPMENT SYSTEMS, as appropriate for your 
development system, and the IRMX 86 CONFIGURATION GUIDE for more 
information. 


COMMAND CREATION PROCEDURES 


The general procedures for creating a user-designed program that can be 
executed by keyboard command are as follows: 

1. Assuming you will be creating the program on a development 
system, write the program code. 

2. Assemble or compile the program. 

3. Link the program to the appropriate IRMX 86 libraries, including 
the Human Interface library. The link parameters to use depend 
on your type of development system and the type of load module 
desired, as follows: 

Series III, Alternative A - creates a relocatable object 
module in LTL or PIC code. Use LINK86 with the SEGSIZE 
(STACK(u)), MEMPOOL, and BIND controls to generate a 
relocatable object module. Generating an relocatable object 
module is recommended to avoid having to reserve memory at 
system configuration time. 

Series III, Alternative B - creates an absolute object 
module. Use the LINK86 and L0C86 commands and the NOINITCODE 
and SEGSIZE (STACKi(u)) controls to generate the absolute 
code. You must reserve memory space at system configuration 
time to receive the absolute object module. 

Series II - creates an absolute object module (only). Use 
the LINK86 and LOC86 commands with SEGSIZE (STACK(u)) 
control. You must reserve memory space at system 
configuration time to receive the absolute module. 

4. Copy the program module from the development system to the :PR0G: 
directory on the appropriate IRMX 86 diskette by using the Human 
Interface UPCOPY command. 

5. Load and execute the program by typing its command name on the 
user console. 

See either the lAPX 86,88 FAMILY UTILITIES USER’S GUIDE for 8086-BASED 
DEVELOPMENT SYSTEMS or the 8086 FAMILY UTILITIES USER’S GUIDE for 
8080/8085-BASED DEVELOPMENT SYSTEMS, as appropriate for your development 
system, for more information about the LINK86 and LOC86 commands. 
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CHAPTER 6. HUMAN INTERFACE SYSTEM CALLS 


The Human Interface system calls described In this chapter are presented 
in alphabetical sequence without regard to functional organization. A 
functional grouping of the calls according to type is provided in the 
System Call Dictionary in Table 6-1. For each call, the Information is 
organized into the following categories: 

• Brief functional description. 

• Calling sequence format. 

• Input parameter definitions, if applicable. 

• Output parameter definitions, if applicable. 

• Considerations and consequences of call usage. 

• Potential exception codes, and their possible causes. 

Throughout the call descriptions, iRMX 86 data types such as WORD and 
STRING are used. The data types are always capitalized, and they are 
defined in Appendix C. 

If you are a new user of the Human Interface calls, it is suggested that 
you review the calling considerations in Chapter 5 before implementing 
these command processing routines in your source code. Quick review of 
the command format and syntax descripions in Chapter 2, and file handling 
examples in Chapter 4 may also be useful. 

It is also assumed that you are familiar with a number of terms and 
concepts that are common to the iRMX 86 Operating System. If you are 
not, it is suggested that you take the time to read INTRODUCTION TO THE 
iRMX 86 OPERATING SYSTEM and the chapters in the iRMX 86 NUCLEUS 
REFERENCE MANUAL that refer to the terms memory pool and catalog. 
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Table 6~1. System Call Dictionary 


System Call 

Synopsis 

Page 

I/O Processing Calls 

C$GET$INPUT$CONNECTION 

Return an EIOS connection for 
the specified input file. 

6-14 

C$GET$OUTPUT$CONNECTION 

Return an EIOS connection for 
the specified output file. 

6-22 

Command Parsing Calls 

C$GET$CHAR 

Get a character from the command line 

6-13 

C$GET$INPUT$PATHNAME 

Parse the command line return a 
pathname that will identify the 
Standard Input file. 

6-20 

C$GET$PARAMETER 

Parse the command line for the next 
parameter and return it as a 
keyword name and a value. 

6-34 

C$GET$OUTPUT$PATHNAME 

Parse the command line and return 
a pathname that will identify the 
Standard Output file. 

6-31 

C$SET$PARSE$BUFFER 

Parse a buffer other than the 
current command line. 

6-56 

Message Processing Calls 

C$FORMAT$EXCEPTION 

Format a default message into 
a user buffer for a given 
exception code. 

6-11 

C$SEND$CO$RESPONSE 

Send a message to the command 
output (CO) and read a response 
from the command input (Cl). 

6-48 

C$SEND$EO$RESPONSE 

Send a message to the error output 
device (EO) and return a response 
from the error input device (El). 

6-51 
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Table 6-1. System Call Dictionary (continued) 


System Call 

Synopsis 

Page 

Comm< 

and Processing Calls 



C$CREATE$COMMAND$CONNECTION 

C$DELETE$COMMAND$CONNECTION 

C$SEND$COMMAND 


Create a command connection and 
return a token. 

Delete a specific command 
connection. 

Concatenate command lines into 
the data structure created by 
CREATE$COMMAND$CONNECTION and 
then execute command. 
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6-38 


Program Control Call 


C$SET$C0NTR0L$C 


Change calling program's 
CONTROL C semaphore to the 
specified semaphore. 


6-54 
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HUMAN INTERFACE SYSTEM CALLS 


C$CREATE$COMMAND$CONNECTION 

C$CREATE$COMMAND$CONNECTION, a command processing call, establishes a TOKEN 
for a command connection that can be used to combine and invoke 
multiple-line commands without interference from other tasks. 


command$conn = RQ$C$CREATE$COMMAND$CONNECTION(default$ci, default $co, 

reserved$word, 
except $ptr ) ; 


INPUT PARAMETERS 


default $ci 


default $co 


reserved$word 


A WORD containing a TOKEN representing a connection 
that will be used as the ;CI: (console input) for any 
command started using this command connection. 

A WORD containing a TOKEN representing a connection 
that will be used as the :C0: for any commands 
started using this command connection. 

A WORD reserved for future use. Its value should be 
zero (0). 


OUTPUT PARAMETERS 

command$conn A WORD which receives a TOKEN for a command 

connection that subsequently may be used by 
C$SEND$COMMAND and C$DELETE$COMMAND$CONNECTION to 
refer to a particular command stream. 

except$ptr A POINTER to a WORD in which the Human Interface will 

return an exception code. 


DESCRIPTION 

The call creates a data structure and returns a TOKEN for a command 
connection that may be used in conjunction with the C$SEND$C0MMAIH) call. 

It also contains the default :CI: and :CO: connection that must be defined 
by the caller for commands invoked by C$SEND$COMMAND calls. 

This call can be used to Invoke a command programmatically Instead of 
interactively; that is, one command can invoke still another command for 
execution, and so on. 
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EXCEPTION CODES 
E$OK 

E$CONTEXT 


E$DEVFD 


No exceptional conditions were encountered. 

When your task invoked this system call, the call 
Invoked at least one other system call. While the 
Operating System performed the latter call, one of 
the following situations occurred. 

• The Operating System detected a zero value for 
the object directory size. This condition 
occurred because an improper configuration of the 
Human Interface subsystem set the job object 
directory size to zero. 

• The Operating System detected two command 
connections being created simultaneously by two 
tasks in the same job. This condition occurred 
because a programmer miscalculated or disrupted a 
synchronized use of the command connection. 

• The Operating System detected the ; STREAM: device 
in the process of being detached. 

• The job containing the task which invoked this 
system call was not created by the Human 
Interface subsystem. 

• While creating a STREAM file, the Extended I/O 
System was unable to attach the : STREAM: device 
because another task had already Invoked a Basic 
I/O system call to attach the : STREAM: device. 

• The Basic I/O System was unable to attach the 
default $cl or default $co connection parameters. 
This occurred because the Basic I/O System was 
detaching the device on which the connection was 
based. 

Your task forced the Extended I/O System to attempt 
the physical attachment of : STREAM: that had 
formerly been only logically attached. In the 
process of attempting to physically attach : STREAM:, 
the Extended I/O System found that the device and 
the device driver specified in the logical 
attachment were incompatible. The Operating System 
would not have returned this exception code if 
: STREAM: had been properly configured in the 
Extended I/O and/or Basic I/O subsystems. 
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EXCEPTION CODES 
E$EXIST 


E$IO 

E$IOMEM 

E$LIMIT 


(continued) 

When your task Invoked this system call, the call 
invoked at least one other system call. While the 
Operating System performed the latter call, one of 
the following situations occurred. 

• This condition occurred when your task used a 
Human Interface call but was not within a job 
created by the Human Interface subsystem. 

• The parameter default $ci or default $co was not a 
token for a valid object. 

• The Basic I/O System deleted either the parameter 
default$cl or default$co. 

While attempting to attach the parameter default $ci 
or default$co, the Basic I/O System detected an I/O 
error. 

The Basic I/O System job does not currently have a 
block of memory large enough to allow the Human 
Interface to create a stream file. 

When your task invoked this system call, the call 
invoked at least one other system call. While the 
Operating System performed the latter call, one of 
the following situations occurred. 

• While creating the objects needed by this call, 
the Operating System detected the calling task's 
job as already having reached the maximum number 
of objects that can exist simultaneously. This 
condition occurred because an improper 
configuration of the Human Interface subsystem 
set the number of the maximum objects within the 
job too low. 

• The Operating System detected the object 
directory of the calling task's job as already 
reached the maximum object directory size. 

• The job containing the task which Invoked this 
call or the job's default user object is 
currently Involved in more than 255 (decimal) I/O 
operations. 
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EXCEPTION CODES 

E$LIMIT (continued) 

• The job containing the task which invoked this 
call was not created by the Human Interface 
subsystem. 

• The object limit of the Basic I/O System job has 
been exceeded. Refer to the chapter of the 
iRMX 86 CONFIGURATION GUIDE that discusses the 
Basic I/O System. 

• During the process of configuring your 
application system, the Basic I/O System job was 
configured a maximum priority that is too low. 
Specifically, the BIOS maximum prioirity is lower 
than either the DUIB priority or the DEVINFO 
priority. Refer to the iRMX 86 CONFIGURATION 
GUIDE for information regarding the BIOS maximum 
priority. Refer to the GUIDE TO WRITING DEVICE 
DRIVERS FOR THE IRMX 86 AND iRMX 88 I/O SYSTEMS 
for additional information regarding the DUIB and 
DEVINFO. 

The : STREAM: device does not exist. This condition 
occurred because someone failed to configure 
: STREAM: during the configuration of the Extended 
I/O or Basic I/O subsystems. 

E$MEM The memory pool of the job whose task invoked this 

call does not currently have a block of memory large 
enough to allow this system call to run to 
completion. 

E$NOT$CONFIGURED One or more of the following system calls are not 

configured into the system: 


E$LOG$NAME 

$NEXIST 


Call 

Subsystem 

A$ATTACH$FILE 

Basic I/O 

A$ CREATE $ FILE 

Basic I/O 

A$GET$FILE$STATUS 

Basic I/O 

A$OPEN 

Basic I/O 

A$PHYSIGAL$ATTACH$DEVICE 

Basic I/O 

A$ SPECIAL 

Basic I/O 

CATALOG$OBJECT 

Nucleus 

CREATE$COMPOSITE 

Nucleus 

CREATE $MAILB OX 

Nucleus 

CREATE$ SEGMENT 

Nucleus 

CREATE $TASK 

Nucleus 

C RE ATE $ S EMAP HMORE 

Nucleus 

DELETE$COMPOSITE 

Nucleus 


I 
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EXCEPTION CODES 

E$NOT$CONFIGURED 


E$NOT$PREFIX 

E$NO$USER 


E$PARAM 


(continued) 


Call 


Subsystem 


DISABLE$DELETION 

ENABLE $DELETION 

GET$DEFAULT$PREFIX 

GET$TYPE 

LOOKUP$OBJECT 

RECEIVE $CONTROL 

RECEIVE$MESSAGE 

S$CREATE$FILE 

SEND$CONTROL 

SEND$MESSAGE 

SET$ INTERRUPT 

S$GET$CONNECTION$STATUS 

WAIT$ INTERRUPT 


Nucleus 

Nucleus 

Basic I/O 

Nucleus 

Nucleus 

Nucleus 

Nucleus 

Extended I/O 

Nucleus 

Nucleus 

Nucleus 

Extended I/O 

Nucleus 


The ; STREAM; logical name does not refer to either a 
device connection or a file connection. 

When your task invoked this system call, the call 
invoked at least one other system call. While the 
Operating System performed the latter call, one of 
the following situations occurred. 

• The job containing the task which invoked this 
call does not have a default user. This 
indicates that your task used a Human Interface 
call but was not within a job created by the 
Human Interface subsystem. 

• The job containing the task which invoked this 
call has a default user. This default user is 
not a user object. 

• The system call LOOKUP$OBJECT was not configured. 

The Extended I/O System was forced to attempt the 
physical attachment of a ; STREAM: device that had 
formerly been only logically attached. In the 
process of attempting to physically attach the 
: STREAM; device, the Extended I/O System found that 
the logical attachment referred to a file driver 
(named, physical, or stream) that is not configured 
into your system. Hence the physical attachment is 
not possible. The Operating System would not have 
returned this exception code if the ; STREAM; device 
had been properly configured in the Extended I/O 
and/or Basic I/O subsystems. 
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EXCEPTION CODES 
E$ SUPPORT 


E$TIME 

E$TYPE 


(continued) 

When your task invoked this system call, the call 
Invoked at least one other system call. While the 
Operating System performed the latter call, one of 
the following situations occurred. 

• During the process of configuring the Basic I/O 
subsystem, someone improperly configured the 
Named File Driver Table. This table is divided 
into a request part and an I/O system part. 
A$ATTACH$FILE or A$OPEN was configured in the 
request part, but the corresponding entry in the 
I/O system part was not included. Refer to the 
IRMX 86 CONFIGURATION GUIDE for further 
Information. 

• The %NO_CREATE_FILE or the %NO_TRUNCATE macro 
calls were configured into the Basic I/O 
subsystem. 

Your task used a Human Interface call but was not 
within a job created by the Human Interface 
subsystem. 


When your task invoked this system call, the call 
invoked a file-attaching call. While performing the 
file-attaching call, the Operating System detected a 
default $ci or default $co parameter that is not a 
connection. 
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C$DELETE$COMMAND$CONNECTION 

C$DELETE$COMMAND$CONNECTION deletes a command connection object and frees 
the memory used by the connection’s data structures. 

CALL RQ$C$DELETE$COMMAND$CONNECTION(command$conn, except$ptr); 

INPUT PARAMETER 

command$conn A WORD containing a token for a valid command 

connection. 

OUTPUT PARAMETER 

except$ptr A POINTER to a WORD in which the Human Interface 

will return an exception code. 

DESCRIPTION 

This call deletes a command connection object previously defined in a 
C$CREATE$COMMAND$CONNECTION call and releases the memory used by the 
connection’s data structures. 

EXCEPTION CODES 

E$OK No exceptional conditions were encountered. 

B$TYPE The command connection parameter refers to an object 

that is not a command connection object. 
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INPUT PARAMETERS 

buff$p A POINTER to a buffer that will receive a STRING 

from the Human Interface containing a formatted 
exeption message. 

buff$max A WORD that specifies the maximum number of bytes 

that may be contained in the buffer pointed to by 
buf f $p • 

exception$code A WORD containing the exception code value for which 

a message is to be created. 

brevity A required BYTE that must be a "1". This gives the | 

format of the message as follows: 

xxxx: (exception name) 

up to a total length of 30 characters. The 
exception name is provided by the Human Interface 
from an internal table. 


OUTPUT PARAMETER 

except$ptr A POINTER to a WORD in which the Human Interface 

will return an exception code. 


DESCRIPTION 

C$FORMAT$EXCEPTION causes the Human Interface to format a message for the 
exception code. The call concatenates the message to the end of the 
STRING already in the buffer. If a STRING is not already present in the 
buffer, the first byte of the buffer must be a zero. The message added by 
C$FORMAT$EXCEPTION will not be longer than 79 characters. The call will 
handle both environmental and programmer error exception codes. 
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EXCEPTION CODES 
E$OK 
E$PARAM 

E$STRING$BUFFER 


No exceptional conditions were encountered. 

An unknown exception code was given. 

Someone specified a buffer that is too small, 
buffer is pointed to by the buff$p parameter, 
buffer provides for the exception message and 
large enough to contain the message. 


This 
This 
is not 
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C$GET$CHAR 

C$GET$CHAR, a command parsing call, gets a character from the command line. 


char = RQ$C $GET$CHAR (except $ptr); 


OUTPUT PARAMETERS 


char 


except$ptr 


A BYTE containing the next character in the command 
line’s character string. A null (OOH) character 
will be returned when there are no more characters. 

A POINTER to a WORD in which the Human Interface 
will return an exception code. 


DESCRIPTION 

Consecutive calls to GET$CHAR get consecutive characters from the command 
line. All parsing of the comniand line must be done in one task. When 
using C$GET$CHAR in commands, you should ensure that the commands using it 
are syntactically compatible with other commands provided by the Human 
Interface. Note that use of C$GET$CHAR decreases the posslblility that 
the command syntax will remain compatible with future Human Interface 
releases . 


EXCEPTION CODES 


E$OK 


No exceptional conditions were encountered. 


E$CONTEXT Tlie Operating System detected a zero value for the 

object directory size. This indicated that your 
task used a Human Interface call but was not within 
a job created by the Human Interface subsystem. 

E$NOT$CONFIGURED The Nucleus system call LOOKUP$OBJECT was not 

incorporated during system configuration. 


E$TIME Your task used a Human Interface call but was not 

within a job created by the Human Interface 
subsystem. 


6-13 





C$ GET$INPUT$CONNECTION 


C$GET$INPUT$CONNECTION 

C$GET$INPUT$CONNECTION, an I/O processing call, returns an Extended I/O 
System connection to the specified input file. 


connection = RQ$C$GET$INPUT$CONNECTION(name$p , except $ptr); 


INPUT PARAMETER 
name$p 


A POINTER to a STRING containing the pathname of the 
file to be accessed. 


OUTPUT PARAMETERS 

connection A WORD that receives the token for the T$GONNECTION 

object for the specified pathname. 

except$ptr A POINTER to a WORD in which the Human Interface 

will return an exception code. 


DESCRIPTION 

The returned input connection will be open for reading and will have the 
following attributes: 

• Read only 

• Accessible to all 

• Two 1024-byte buffers 

C$GET$INPUT$CONNECTION may display one of the following messages on :C0; 
if an unusual or disallowed operation is encountered; 

pathname, file not found 

meaning that the input file does not exist, or; 

pathname, READ access required 

meaning that the user is not allowed read access to the input file. 
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DESCRIPTION (continued) 

C$GET$INPUT$CONNECTION causes an error message to be displayed whenever an 
exceptional condition is encountered. The exceptional condition that 
triggers the error message can be either one of those listed for 
C$GET$INPUT$CONNECTION or from the Extended I/O System calls S$ATTACH$FILE 
and S$OPEN. 

The error message has the form: 
pathname, xxxx:exception code 
where: 

pathname Pathname of the file or directory that was being 

accessed when the exceptional condition was detected. 

xxxx Four-digit value of the exception code. 

exception code One of the exception codes defined under "Exception 

Codes" in this call description. 


EXCEPTION CODES 

E$OK No exceptional conditions were encountered. 

E$CONTEXT When your task invoked this system call, the Human 

Interface call invoked at least one other system 
call. While the Operating System performed the 
latter call, one of the following situations 
occurred. 

• The Operating System detected a zero value for 
the object directory size. This indicates that 
your task used a Human Interface call but was not 
within a job created by the Human Interface 
subsystem. 

• The Basic I/O subsystem determined that the 
device referenced by the name$p parameter was in 
the process of being detached. 

• The job containing the task which invoked this 
system call was not created by the Human 
Interface subsystem. 

• While processing a file-attaching system call, 
the Extended I/O System was unable to attach the 
device containing the file, referenced by the 
name$p parameter. This occurred because the 
Basic I/O System has already attached the device. 
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EXCEPTION CODES 
E$DEVFD 


E$FACCESS 


E$FNEXIST 


E$FTYPE 


E$ILLVOL 


The Extended I/O System was forced to attempt the 
physical attachment of a device that had formerly 
been only logically attached. In the process of 
attempting to physically attach the device, the 
Extended I/O System found that the device and the 
device driver specified in the logical attachment 
were incompatible. The Operating System would not 
have returned this exception code if the device 
referenced by the name$p parameter had been properly 
configured in the Extended I/O and/or the Basic I/O 
subsystems. 

The access rights embedded in the connection have 
prohibited you from opening the file in the read 
mode. This exceptional condition can arise only 
when the connection refers to named files. 

While attaching the file specified in the name$p 
parameter, the Operating System detected one of the 
following circumstances: 

• Either some file in the specified pathname 
(referenced by the name$p parameter), or the 
target file Itself, is marked for deletion. 

• Either some file in the specified pathname 
(referenced by the name$p parameter), or the 
target file itself, does not exist. 

The Operating System detected an error in the 
pathname specified by the name$p parameter. The 
pathname included the name of a data file as a 
directory. For example, the pathname A/B/C assumes 
that A and B are names for directories. This 
exception code would have been returned if either A 
or B was actually a data file. 

While attaching the file pointed to by the name$p 
parameter, the file attaching call forced the 
Extended I/O System to attempt the physical 
attachment of the device as a named device. This 
device had formerly been only logically attached. 

In the process of attempting to physically attach 
the device, the Extended I/O System examined the 
volume label and found that the volume does not 
contain named files. This prevented the Extended 
I/O System from completing physical attachment 
because the named file driver was requested during 
logical attachment. 


6-16 


C$GET$INPUT$CONNECTION 


EXCEPTION CODES 
E$IO 

E$IOMEM 

E$LIMIT 


E$LOG$NAME 

$NEXIST 

E$MEDIA 


(continued) 

An I/O error occurred while trying to access the 
file given in the name$p parameter. 

While attempting to create a connection, memory from 
the Basic I/O subsystem's memory pool was needed. 
However, the Basic I/O System job does not currently 
have a block of memory large enough to allow this 
system call to run to completion. 

When your task invoked this system call, the call 
invoked at least one other system call. While the 
Operating System performed the latter call, one of 
the following situations occurred. 

• The Extended I/O subsystem created enough objects 
to exceed the object limit of the Basic I/O 
System job. Refer to the chapter of the iRMX 86 
CONFIGURATION GUIDE that discusses the Basic I/O 
System. 

• During the process of configuring your 
application system, the Basic I/O System job was 
configured a maximum priority that is too low. 
Specifically, the BIOS maximum priority is lower 
than either the DUIB priority or the DEVINFO 
priority. Refer to the iRMX 86 CONFIGURATION 
GUIDE for information regarding the BIOS maximum 
priority. Refer to the GUIDE TO WRITING DEVICE 
DRIVERS FOR THE IRMX 86 AND iRMX 88 I/O SYSTEMS 
for additional information regarding the DUIB and 
DEVINFO. 

• While processing a file-attaching system call or 
connection opening system call, the Operating 
System detected either of the two following 
situations: the calling task's job or the job's 
default user object is currently involved in more 
than 255 (decimal) I/O operations. 

• The job containing the task which invoked this 
system call was not an I/O job created by the 
Human Interface subsystem. 

The specified pathname for the specified device 
(referenced by the name$p parameter) contains an 
explicit logical, name. The Extended I/O System, 
however, was unable to find this name in the object 
directories of the local job, the global job, and 
the root job. 

The Operating System detected that the device 
containing the specified file (referenced by the 
name$p parameter) was not online. 


6-17 



C$GET$INPUT$CONNECTION 


EXCEPTION CODES (continued) 


E$MEM The memory pool of the calling task's job as not 

currently having a block of memory large enough to 
allow this system call to run to completion. 

E$NO$PREFIX The pathname specified in the name$p parameter of 

this call contained no explicit prefix (no logical 
name), so the Extended I/O System attempted to use 
the default prefix. However, the default prefix is 
either undefined, or it is not a valid device 
connection or file connection. 


E$NOT$CONFIGURED There are two possible conditions that can cause the 

Human Interface System to return this call: 


• When your task Invoked this system call, it 
forced the Extended I/O System to attempt the 
physical attachment of the device referenced by 
the name$p parameter. This device had formerly 
been only logically attached. In the process of 
attempting to physically attach the device, the 
Extended I/O System found that the logical 
attachment referred to a file driver (named, 
physical, or stream) that was not configured into 
your system. 


• At least one of the following system calls was 
left out of the system during the configuration 
process: 


Call 


Subsystem 


A$ATTACH$FILE 

A$GET$FILE$STATUS 

A$OPEN 

A$PHYSICAL$ATTACH$DEVICE 

A$SPECIAL 

CREATE$COMPOSITE 

CREATE$MAILBOX 

CREATE$SE(3iENT 

DELETE$COMPOSITE 

DISABLE$DELETION 

ENABLE $DELETION 

GET$DEFAULT$PREFIX 

GET$TYPE 

LOOKUP$OBJECT 

RECEIVE$CONTROL 

RECEIVE$MESSAGE 

S$ATTACH$FILE 

SEND$CONTROL 

SEND$MESSAGE 

SET$ INTERRUPT 

S$OPEN 

WAIT$ INTERRUPT 


Basic I/O 

Basic I/O 

Basic I/O 

Basic I/O 

Basic I/O 

Nucleus 

Nucleus 

Nucleus 

Nucleus 

Nucleus 

Nucleus 

Basic I/O 

Nucleus 

Nucleus 

Nucleus 

Nucleus 

Extended I/O 

Nucleus 

Nucleus 

Nucleus 

Extended I/O 

Nucleus 
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EXCEPTION CODES (continued) 

E$NOT$PREFIX The pathname specified by the name$p parameter 

contained a logical name. The name referred to an 
object that was neither a device connection nor a 
file connection. 

E$NO$USER The job containing the task which invoked this call 

does not have a default user or the default user of 
this calling task’s job was not a user object. 

E$PARAM When your task Invoked this system call, the call 

invoked at least one other system call. While the 
Operating System performed the latter call, one of 
the following situations occurred. 

• The pathname specified by the name$p parameter 
contained a logical name. The name was either 
longer than 12 characters or contained invalid 
characters. 

• The system call forced the Extended I/O System to 
attempt the physcial attachment of the device 
referenced by the name$p parameter. The device 
had formerly been only logically attached. In 
the process of attempting to physically attach 
the device, the Extended I/O System found that 
the logical attachment referred to a file driver 
(named, physical, or stream) that is not 
configured into your system. Hence the physical 
attachment is not possible. 

E$PREFIX$SYNTAX The Operating System detected a colon (:) at the 

start of the pathname specified by the name$p 
parameter. This indicates that the pathname 
contains a logical name. However, the Operating 
System was unable to find a second colon to 
terminate the logical name. 

E$SHARE The Operating System detected some other ta?k in 

your system using the I/O System to manipulate the 
file through another connection. That task 
requested that the I/O System restrict the sharing 
of the file to certain modes. Your task attempted 
to use a read only mode that precludes sharing the 
file. 

E$TIME Your task used a Human Interface call but was not 

within a job created by the Human Interface 
subsystem. 
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C $GET$INPUT$PATHNAME 

C$GET$INPUT$PATHNAME, an I/O processing call, returns a pathname that may 
be used as the Standard Input. 


CALL RQ$C$GET$INPUT$PATHNAME(path$name$p, path$name$max, except$ptr) 


INPUT PARAMETER 

path$name$max A WORD that specifies the length In bytes of the 

string pointed to by the path$name$p parameter, 
where the maximum length that may be specified for a 
pathname Is 255 characters, plus one extra byte. 


OUTPUT PARAMETERS 

path$name$p A POINTER to a buffer that will receive a STRING 

containing the next pathname In the Standard Input. 
A zero-length string Indicates that there are no 
more pathnames. 

except$ptr A POINTER to a WORD In which the Human Interface 

will return an exception code. 


DESCRIPTION 

The pathname returned by C$GET$ I NPUT$ PATHNAME may be used for the 
following purposes: 

«! In calls to the Extended I/O System. 

• In a call to C$GET$INPUT$CONNECTION, to obtain a connection. 

The pathname will be a single pathname from the command line’s Input 
list. The next file In the Input sequence may then be requested by making 
successive calls to C$GET$INPUT$ PATHNAME. The end of the pathname-list Is 
denoted by a zero-length string In the path$name$p buffer. 


EXCEPTION CODES 

E$OK No exceptional conditions were encountered. 
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EXCEPTION CODES (continued) 

E$CONTEXT The Operating System detected a zero value for the 

object directory size. This indicates that your 
task used a Human Interface call but was not within 
a job created by the Human Interface subsystem. 

E$EXTRA$SO There were no more input pathnames although the 

output pathname list was not exnq>ty. For example, 
file E is considered an extra pathname in the 
command entry A,B TO C,D,E. 

E$LIMIT While creating an object, the Operating System 

detected a job’s object limit having been exceeded. 
The job contained the task which invoked this system 
call. 

E$LIST The last value of the input pathname list is 

missing. For example, ABLE, BAKER, has no value 
following the second comma. 

E$MEM The memory pool of the calling task’s job as not 

currently having a block of memory large enough to 
allow this latter system call to run to completion. 

E$NOT$CONFIGURED One or both of the following Nucleus System calls 

were not Incorporated during system configuration: 

LOOKUP$OBJECT 

CREATE$SEGMENT 

E$PARSE$TABLES The Human Interface subsystem detected an error that 

should not occur unless someone inadvertently alters 
an internal table used by this subsystem. 

E$STRING The pathname to be returned exceeds the length limit 

of 255 characters. 

E$STRING$BUFFER Someone specified a buffer that is too small. This 

buffer was pointed to by the path$name$p parameter 
and was not large enough for the pathname to be 
returned. 

E$TIME Your task used a Human Interface call but was not 

within a job created by the Human Interface 
subsystem. 
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C$GET$OUTPUT$CONNECTION 

C$GET$OUTPUT$CONNECTION, an I/O processing call, parses the conunand line 
and returns an Extended I/O System connection refering to the requested 
output file. 


connection = RQ$C$GET$OUTPUT$CONNECTION(name$p , preposition, 

except$ptr ) ; 


INPUT PARAMETERS 

name$p A POINTER to a STRING containing the pathname of the 

file to be accessed. 

preposition A BYTE that defines which preposition to use to 

create the output file. Use one of the following 
values to specify the preposition mode: 

Meaning 

Use same preposition as was 
returned by the last 
GET$OUTPUT$PATHNAME call. 

TO 

OVER 
AFTER 
error 


Value 


1 

2 

3 

4-255 


OUTPUT PARAMETERS 

connection A WORD containing a token for an Extended I/O System 

connection object for the file specified when the 
call is Invoked. 

except$ptr A POINTER to a word in which the Human Interface 

will return an exception code. 
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DESCRIPTION 

The returned output connection will be open for writing and will have the 
following attributes: 

• Write only 

• Accessible to all 

• Two 1024-byte buffers 


C$GET$OUTPUT$CONNECTION may issue one of the following prompts on :C0: if 
the user attempts to perform an unexpected or disallowed operation: 

pathname, already exists, DELETE? 

meaning that the TO preposition was used and the output file already 
exists, or: 

pathname, DELETE access required 

meaning that the pre-existing file or directory cannot be deleted without 
delete access to the file or directory, or: 

pathname, directory ADD entry access required 

meaning that the file is a directory and the user does not have add entry 
access to it. 

C$GET$OUTPUT$CONNECTION causes an error message to be displayed whenever 
an exceptional condition is encountered. The exceptional condition that 
triggers the error message can be either one of those listed for 
C$GET$OUTPUT$CONNECTION or from an Extended I/O System call. 

The error message has the form: 

pathname, xxxx: except ion code name 


where: 


pathname 


Pathname of the file or directory that was being 
accessed when the exceptional condition was detected. 


xxxx 


Four-digit value of the exception code. 


exception code One of the exception codes defined under "Exception 
name Codes" in this call description. 
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EXCEPTION CODES 
E$OK 

E$CONTEXT 


E$DEVFD 


E$FACCESS 


No exceptional conditions were encountered. 

When your task invoked this system call, the call 
invoked at least one other system call. While the 
Operating System performed the latter call, one of 
the following situations occurred. 

• The Operating System detected a zero value for 
the object directory size. This indicates that 
your task used a Human Interface call but was not 
within a job created by the Human Interface 
subsystem. 

• The device referenced by the name$p parameter was 
in the process of being detached. 

• The Extended I/O System was unable to attach the 
device containing the file because the Basic I/O 
System has already attached the device. 

A system call forced the Extended I/O System to 
attempt the physical attachment of the device 
referenced by the name$p parameter. This device had 
formerly been only logically attached. In the 
process of atten5>ting to physically attach the 
device, the Extended I/O System found that the 
device and the device driver specified in the 
logical attachment were incompatible. The Operating 
System would not have returned this exception code 
if the device referenced by the name$p parameter had 
been properly configured in the Extended I/O and/or 
the Basic I/O subsystems. 

When your task Invoked this system call, the call 
invoked at least one other system call. While the 
Operating System performed the latter call, one of 
the following situations occurred. 

• While in the process of creating a file, the 
Operating System detected the user as not having 
update access to an existing file and/or as not 
having add-entry access to the parent directory. 

• While performing a connection opening call, the 
access rights embedded in the connection have 
prohibited you from opening the file in write 
mode. This exceptional condition can arise only 
when the connection refers to a named data file 
or directory and the file is already open. 
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EXCEPTION CODES 

E$FACCESS (continued) 


E$FNEXIST 


E$FTYPE 


E$ILLVOL 


E$IO 

E$IOMEM 


E$LIMIT 


• While performing a system call that removes 
Information from the end of a named data file, 
the Operating System detected that the user does 
not have update access to the file. 

The Operating System detected one of the following 
circumstances: 

• Either some file in the pathname specified by 
the name$p parameter is marked for deletion. 

• Either some file in the pathname specified by 
the name$p parameter, or the target file itself, 
does not exist. 

The Operating System detected an error in the 
pathname specified by the name$p parameter. The 
pathname Included the name of a data file as a 
directory. For example, the pathname A/B/C assumes 
that A and B are names for directories. This 
exception code would have been returned if either A 
or B was actually a data file. 

When the Operating System performed the call that 
attaches or creates a file, the call forced the 
Extended I/O System to attempt the physical 
attachment of the device referenced by the name$p 
parameter. This device had formerly been only 
logically attached. In the process of attempting 
to physically attach the device, the Extended I/O 
System examined the volume label and found that the 
volume does not contain named files. This 
prevented the Extended I/O System from completing 
physical attachment because the named file driver 
was requested during logical attachment. 

An I/O error occurred while trying to access or 
create the file given in the name$p parameter. 

The memory required to create a connection was part 
of a Basic I/O System memory pool. However, the 
Basic I/O System job does not currently have a 
block of memory large enough to allow this system 
call to run to completion. 

When your task invoked this system call, the call 
invoked at least one other system call. While the 
Operating System performed the latter call, one of 
the following situations occurred. 
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EXCEPTION CODES 

E$LIMIT (continued) 

• While creating the objects needed by this call, 
the Operating System detected the calling task*s 
job as already having reached the maximum number 
of objects that can exist simultaneously. 

• While processing the latter system call, the 
Operating System detected either of the two 
following situations: the calling task's job, or 
the job's default user object, is currently 
involved in more than 255 (decimal) I/O 
operations. 

• The job containing the task which invoked this 
call wa not created by the Human Interface 
subsystem. 

• A subsystem created enough objects to exceed the 
object limit of the Basic I/O System job. Refer 
to the chapter of the iRMX 86 CONFIGURATION 
GUIDE that discusses the Basic I/O System. 

• During the process of configuring your 
application system, the Basic I/O System job was 
configured a maximum priority that is too low. 
Specifically, the BIOS maximum priority is lower 
than either the DUIB priority or the DEVINFO 
priority. Refer to the IRMX 86 CONFIGURATION 
GUIDE for information regarding the BIOS maximum 
priority. Refer to the GUIDE TO WRITING DEVICE 
DRIVERS FOR THE iRMX 86 AND iRMX 88 I/O SYSTEMS 
for additional information regarding the DUIB 
and DEVINFO. 

While processing a file-attaching call, the 
Operating System detected the following: the 
pathname specified in the name$p parameter contains 
an explicit logical name. The Extended I/O System, 
however, was unable to find this name in the object 
directories of the local job, the global job, and 
the root job. 

E$MEDIA The device specified by the name$p parameter was 

not online. 


E$LOG$NAME 

$NEXIST 
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EXCEPTION CODES (continued) 

E$MEM When your task invoked this call, the call invoked 

at least one other system call. \*Jhile processing 
this latter call, the Operating System detected the 
memory pool of the calling task’s job as not 
currently having a block of memory large enough to 
allow this system call to run to completion. To be 
more specific, if the latter call was attempting to 
process a file-attaching system call, a 
file-creating system call, or a connection opening 
system call, then the creation or the opening of a 
connection was not completed. 

E$NO$PREFIX The pathname specified by the name$p parameter of 

this call contained no explicit prefix (no logical 
name), so the Extended I/O System attempted to use 
the default prefix. However, the default prefix is 
either undefined, or it is not a valid device 
connection or file connection. 

E$NOT$CONFIGURED There are two possible conditions that can cause 

the Human Interface System to return this call: 

• When your task Invoked this system call, it 
forced the Extended I/O System to attempt the 
physical attachment of the device referenced by 
the name$p parameter. This device had formerly 
been only logically attached. In the process of 
attempting to physically attach the device, the 
Extended I/O System found that the logical 
attachment referred to a file driver (named, 
physical, or stream) that was not configured 
into your system. 

• At least one of the following system calls was 
left out of the system during the configuration 
process: 


Call 

Subsystem 

A$ATTACH$FILE 

Basic I/O 

A$CREATE$FILE 

Basic I/O 

A$GET$FILE$STATUS 

Basic I/O 

A$OPEN 

Basic I/O 

A$PHYS ICAL$ATTAC H$DEVICE 

Basic I/O 

A$READ 

Basic I/O 

A$SEEK 

Basic I/O 

A$SPECIAL 

Basic I/O 

A$TRUNCATE 

Basic I/O 

A$WRITE 

Basic I/O 

CREATE$COMPOSITE 

Nucleus 

CREATE$MAILBOX 

Nucleus 
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EXCEPTION CODES 

E$NOT$CONFIGURED 


E$NOT$PREFIX 

E$NO$USER 

E$PARAM 


(continued) 


Call Subsystem 


CREATE$SEGMENT 

Nucleus 


DELETE$COMPOSITE 

Nucleus 


DISABLE$DELETION 

Nucleus 


ENABLE$DELETION 

Nucleus 


GET$DEFAULT$PREFIX 

Basic I/O 

GET$TYPE 

Nucleus 


LOOKUP$OBJECT 

Nucleus 


RECEIVE $CONTROL 

Nucleus 


RECEIVE$MESSAGE 

Nucleus 


S$ATTACH$FILE 

Extended 

I/O 

S$CREATE$FILE 

Extended 

I/O 

SEND$CONTROL 

Nucleus 


SEND $MES SAGE 

Nucleus 


SET$INTERRUPT 

Nucleus 


S$GET$CONNECTION$ STATUS 

Extended 

I/O 

S$OPEN 

Extended 

I/O 

S$READ$MOVE 

Extended 

I/O 

S$SEEK 

Extended 

I/O 

S$TRUNCATE$FILE 

Extended 

I/O 

S$WRITE$MOVE 

Extended 

I/O 

WAIT$INTERRUPT 

Nucleus 



The pathname specified by the name$p parameter 
contained a logical name. The name referred to an 
object that was neither a device connection nor a 
file connection. 

Your task used a Human Interface call but was not 
within a job created by the Human Interface 
subsystem. 

When your task invoked this system call, the call 
invoked at least one other system call. While the 
Operating System performed the latter call, one of 
the following situations occurred. 

• The Operating System detected the pathname 

specified by the name$p parameter containing a 
logical name. The logical name was either 
longer than 12 characters or contained invalid 
characters. 
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EXCEPTION CODES 

E$PARAM (continued) 

• The system call forced the Extended I/O System 
to attempt the physcial attachment of the device 
referenced by the name$p parameter. The device 
had formerly been only logically attached. In 
the process of attempting to physically attach 
the device, the Extended I/O System found that 
the logical attachment referred to a file driver 
(named, physical, or stream) that is not 
configured into your system. Hence the physical 
attachment is not possible. 

E$PREFIX$SYNTAX The Operating System detected a colon (:) at the 

start of the pathname specified by the name$p 
parameter. This Indicates that the pathname 
contains a logical name. However, the Extended I/O 
System was unable to find a second colon to 
terminate the logical name. 

E$PREPOSITION Someone used a zero as the preposition value. This 

indicated that the same preposition was to be used 
as in the last C$GET$OUTPUT$PATHNAME call. 
Unfortunately, C$GET$OUTPUT$PATHNAME has not been 
called. 

E$SHARE When your task invoked this system call, the call 

invoked at least one other call. While the 
Operating System performed the latter call, one of 
the following situations occurred. 

• While attempting to open a connection so that 
your task could access the file through the 
connection, the Operating System detected the 
following: Some other task in your system is 
using the I/O System to manipulate the file 
through another connection. That task requested 
that the I/O System restrict the sharing of the 
file to certain modes. Your task attempted to 
use a mode that precludes sharing the file. 

• While attempting to open a connection so that 
your task could access the file through the 
connection, the Operating System detected your 
task attempting to open a directory for writing 
only. 

• While processing a file-creating system call, 
your task attempted to create a file that 
already exists. Consequently, the Extended I/O 
System must truncate the file to zero length. 
However, the Extended I/O System cannot do this 
because, when the file was initially created, 
the owner specified that it could not be shared 
with writers. 
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EXCEPTION CODES 
E$ SPACE 


E$SUPPORT 


E$TIME 


When your task invoked this system call, the call 
Invoked at least one other call. While the 
Operating System performed the latter call, one of 
the following situations occurred. 

• While attempting to create a file or write into 
a file, the Operating System detected that there 
was no more space on the volume. 

• While attempting to create a file, the Operating 
System detected that the Extended I/O System had 
run out of f nodes on the volume. Refer to the 
FORMAT command in this manual. 

Either the %NO_CREATE_FALSE or the %NO_TRUNCATE 
macro call was configured into the Basic I/O 
subsystem. 

Your task used a Human Interface call but was not 
within a job created by the Human Interface 
subsystem. 
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C$GET$OUTPUT$PATHNAME 


C$GET$OUTPUT$PATHNAME parses the command line and returns a pathname that 
refers to the Standard Output file or device. 


preposition = RQ$C$GET$OUTPUT$PATHNAME(path$name$p , path$name$max, 

default $output$p, except$ptr); 


INPUT PARAMETERS 

path$name$max A WORD that indicates the maximum size (in bytes) 

of the path$name$ string. Since the maximum size 
of the buffer is 256 bytes, the maximum allowable 
size for individual pathnames is 255 characters 
plus one extra byte. 

default$output$p A POINTER to a STRING containing the command's 

default Standard Output. If a TO/OVER/AFTER 
preposition is not encountered in the connnand line 
being processed, the text of this parameter will be 
used as though it had appeared on the command 
line. The text must specify TO, OVER, or AFTER for 
the output mode. Examples: TO :C0: or TO ;LP:. 


OUTPUT PARAMETERS 


preposition 


path$name$p 


except$ptr 


A BYTE describing the preposition type that 
C$GET$OUTPUT$PATHNAME encountered. This value may 
be passed to C$GET$OUTPUT$CONNECTION if a 
connection to the file is desired. The value will 
be one of the following: 


Value 


Meanint 


1 TO 

2 OVER 

3 AFTER 


A POINTER to a buffer that will receive a STRING 
containing the next pathname in the Standard 
Output. A null (zero-length) name will be returned 
if no Standard Output pathnames were given and no 
default$output parameter was specified (a zero 
pointer or null string). 

A POINTER to a WORD in which the Human Interface 
will return an exception code. 
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DESCRIPTION 

The pathname returned by C$GET$OUTPUT$PATHNAME may be used for the 
following purposes: 

• In calls to the Extended I/O System. If the Extended I/O System 
is used, the interpretation of the TO /OVER/AFTER prepositions 
will be the user*s responsibility. 

• In a call to C$GET$OUTPUT$CONNECTION to obtain a connection. 

On the command line, the Standard Output is denoted by the appearance of 
the TO/OVER/ AFTER preposition. See "Parameter Parsing" in Chapter 5. 

Further calls to C$GET$OUTPUT$PATHNAME will return additional pathnames, 
either to the next file in the output list, or to the same pathname for a 
concatenation operation. 


EXCEPTION CODES 
E$OK 

E$CONTEXT 

E$DEFAULT$SO 


E$LIMIT 

E$LIST 


E$MEM 


No exceptional conditions were encountered. 

The Operating System detected a zero value for the 
object directory size. This indicates that your 
task used a Human Interface call but was not within 
a job created by the Human Interface subsystem. 

The default output name STRING is invalid for one 
or more of the following reasons: 

• The preposition given is not TO, OVER, or AFTER 

• The parameter default$output$p does not contain 
a pathname. 

• Someone did not specify an output preposition 
on the command line and a default was not given 

The calling job’s object limit was exceeded while 
the objects needed by this call were being created. 

One of the following conditions exist: 

• The input pathnames contain unmatched 
parentheses. 

• The last value of input pathname list is 
missing. For example, ABLE, BAKER, has no value 
after the second comma. 

The memory pool of the job containing the task 
which invoked this call does not currently have a 
block of memory large enough to allow this system 
call to run to completion. 
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EXCEPTION CODES (continued) 

E$NOT$CONFIGURED One or both of the following Nucleus System calls 
were not incorporated during system configuration: 

CREATE$SEGMENT 
L00KUP$0 EJECT 

E$PARSE$TABLES The Human Interface subsystem dectected an error 

that should not occur unless someone alters an 
internal table used by this subsystem. 

E$STRING The pathname to be returned exceeds the length 

limit of 255 characters. 

E$STRING$BUFFER Someone created a buffer to which the parameter 

path$natne$p points. This buffer was not large 
enough for the pathname to be returned. 

E$TIME Your task used a Human Interface call but was not 

within a job created by the Human Interface 
subsystem. 


6-33 



C$GET$PARAMETER 


C$GET$PARAMETER 

GET$PARAMETER parses the command line to find one parameter and returns 
it as a keyword name and a list of values. 


more = RQ$C$GET$PARAMETER(name$p , name$max, value$p, value$max, 

lndex$p, predict $list$p, except $ptr); 


INPUT PARAMETERS 


name$max 


A WORD that contains the length of the 
user-supplied buffer (in bytes) specified by name$p. 


value $max 


A WORD that contains the length of the 
user-provided buffer specified in value$p. 


predict$list$p A POINTER to a STRING$TABLE , as described in 

Appendix C, that contains the predicted 
prepositions. The predict$llst$p POINTER should be 
zero if the preposition prediction function is not 
being used for the command. 


I 


OUTPUT PARAMETERS 


more 


name$p 


value$p 


A BYTE value that indicates whether or not the 
current call to C$GET$PARAMETER returned a 
parameter. A value of OOh indicates there are no 
more parameters; a value of OFFh Indicates that a 
parameter was returned. 

A POINTER to the buffer that receives the parameter 
keyword STRING. If a keyword did not exist for the 
parameter, a null (zero-length) string will be 
returned. The size of the buffer must be one byte 
longer than the largest expected parameter keyword 
or preposition. 

A POINTER to a buffer that will receive a 
STRING$TABLE, as described in Appendix C. The 
value-part will be stored as a STRING$TABLE in the 
buffer. If the parameter had multiple values, the 
STRING$TABLE entry would return one value per 
string. 
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OUTPUT PARAMETERS (continued) 

index$p A POINTER to a BYTE that receives the index to the 

predict $list$p entry that corresponds to the name$p 
contents. If predict$list$p is empty or if the 
parameter name is not found in the predict list, 
the index will be zero; that is, the index will be 
non-zero only if a preposition is found. 

except$ptr A POINTER to a WORD in which the Human Interface 

will return an exception code. 


DESCRIPTION 

C$GET$PARAMETER parses one parameter and returns it as a keyword name and 
a value. A parameter may be one of the following: 

• ke 3 Tword parameter using parenthesis 

• keyword parameter using equal sign 

• preposition parameter 

• list of values 

A description of the types, format, and syntax of acceptable parameters 
is provided in Chapter 5 under "Parameter Parsing." 

A STRING$TABLE is the structure used to implement the predict$list 
table. Any parameter you define in the predict $list table must be used 
as a preposition. You will also need to provide a STRING$TABLE entry 
containing the prepositions that C$GET$PARAMETER may encounter; that is, 
unless you provide some external semantics in a STRING$TABLE, the parsing 
routines have no way of distinguishing a preposition parameter from two 
keyword parameters. See Appendix C for a description and format of a 
STRING$TABLE . 


EXCEPTION CODES 

E$OK No exceptional conditions were encountered. 

E$CONTEXT The Operating System detected a zero value for the 

object directory size. This indicates that your 
task used a Hum^n Interface call but was not within 
a job created by the Human Interface subsystem. 

E$CONTINUED The Operating System detected a continuation 

character in the parse buffer while performing the 
system call. This condition should only occur 
while parsing the contents of a buffer other than 
the command line buffer. 
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EXCEPTION CODES (continued) 

E$LIST One of the following conditions exist: 

• The parameter contains unmatched parenthesis. 

• A value in the value list is missing or an 
improper value was entered. Examples of both 
these conditions follow: 

Value Comment s 

A,B, No value following second comma. 

A, B,C Space between first comma and B. 

A,B=C,D The equal sign can not be used 

unless it is between quotes: 'B=C 
is proper. 

A,B(C,E),F The parentheses can not be used 
unless between quotes. 

E$LITERAL The Operating System detected a literal (quoted 

string) in the parse buffer with no closing quote. 
This condition should only occur while parsing the 
contents of a buffer other than the command line 
buffer. 

E$NOT$CONFIGURED The Nucleus System call LOOKUP$OBJECT was not 

incorporated during system configuration. 

E$PARSE$ TABLES The Human Interface subsystem has detected an error 

that should not occur unless someone inadvertently 
alters an internal table used by this subsystem. 

E$SEPARATOR The Operating System detected a command separator 

in the parse buffer while performing this system 
call. This condition should only occur while 
parsing the contents of a buffer other than the 
command line buffer. The following is a list of 
the command separators: X, <>, j|, |, [, and ]. 

E$STRING One or more of the following conditions exist: 

• The string to be returned as the parameter name 
exceeds the length limit of 255 characters. 

• One of the parameter values to be returned 
exceeds 255 characters in length. 

E$STRING$BUFFER One or more of the following conditions exist: 

• The string to be returned as the parameter name 
exceeds the buffer size provided by the user in 
the call. 
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EXCEPTION CODES 

E$STRING$ BUFFER 

E$TIME 


(continued) 

• The parameter values to be returned exceed the 
value-buffer size provided by the user in the 
call. 

Your task used a Human Interface call but was not 
within a job created by the Human Interface 
subsystem. 
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C$SEND$COMMAND 


C$SEND$COMMAND, a command processing call, accepts command lines as read 
from the user's console and concatenates them into the data space created 
by the C$CREATE$COMMAND$CONNECTION call. 


CALL RQ$C$SEND$COMMAND(command$conn, line$p, command $except$ptr, 

except$ptr) ; 


INPUT PARAMETERS 

command$conn A WORD containing a TOKEN for a command connection, 

where the connection was created by a 
C$CREATE$COMMAND$CONNECTION call. 

line$p A POINTER to a STRING containing a command to 

execute. 


OUTPUT PARAMETERS 

command$except$p tr A POINTER to a WORD that receives the status of the 

invoked command while it is being executed. This 
parameter is undefined if an exceptional condition 
code is returned in the exception pointer. 

except$ptr A POINTER to a WORD in which the Human Interface 

will return the exception code for an exception 
that occured while the command was being loaded. 


DESCRIPTION 

C$SEND$COMMAND accepts command lines and combines them into the data 
space created by the C$CREATE$COMMAND$CONNECTION call. The general 
structure of a command line is as follows: 

command-pathname inpath-list [preposition outpath-llst ] [parameters] 

The command-pathname contains the pathname of the object file of the 
program that is to be loaded by the Application Loader. 

As described in greater detail in this manual's chapter on command entry 
and syntax, a command line entry may contain several continuation marks. 
The continuation mark Indicates that the command line is continued on the 
next line. If the command line is continued on another line, an 
E$CONTINUED exception code value is returned, the command is not 
executed, and control returns to the caller. 
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DESCRIPTION (continued) 

If a scan of the command line is successful, the command-pathname entered 
in the line$p parameter is parsed. If no exception conditions halt the 
process at this point, the Human Interface sybsystem requests the 
Application Loader to execute the command. 

An Application Loader call creates an I/O job and then the Application 
Loader validates the header, group definition and segment definition 
records of the object file of the program to be executed. Refer to the 
8086 FAMILY UTILITIES USER’S GUIDE for explanations of segments, groups 
and object file formats. 

C$SEND$COMMAND returns two exception codes: one for the C$SEND$COMMAND 
call and one for the Invoked command. The except $ptr parameter returns 
the C$SEND$ COMMAND exceptional conditions, as decribed under the 
EXCEPTION CODES heading in this command description. The command’s 
except $ptr returns the invoked command’s exceptional condition codes, and 
these are defined by the Invoked command. The E$C0NTR0L$C exception code 
can be received at either place. 


EXCEPTION CODES 


E$0K 


No exceptional conditions were encountered. 


E$BAD$GROUP 

E$BAD$HEADER 


E$BAD$SEGMENT 

E$CHECKSUM 


E$C0NTEXT 


The object file represented by the command-pathname 
contained an invalid group definition record. 

The object file represented by the command-pathname 
does not begin with a header record for a loadable 
object module. 

The object file represented by the command-pathname 
contained an invalid segment definition record. 

At least one record of the object file represented 
by the command-pathname contains a checksum error. 
This situation could occur if the CHECKSUM amount 
calculated during the read operation did not match 
the CHECKSUM field of the record being read. 

When your task invoked this system call, the Human 
Interface call invoked at least one other system 
call. While the Operating System performed the 
latter call, one of the following situations 
occurred. 


• The Operating System detected a zero value for 
the object directory size. This indicated that 
your task was not within a job created by the 
Human Interface subsystem. 
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EXCEPTION CODES 

E$CONTEXT (continued) 

• The Operating System detected the device 
containing the object file of the 
command-pathname was in the process of being 
detached. 

• The Operating System detected a situation where 
the calling task's job was not created by the 
Human Interface subsystem. 

• The Extended I/O System was unable to attach 
the device containing the object file 
represented by the command-pathname because the 
Basic I/O System has already attached the 
device. 

• The Operating System detected a 

command -pathname that refers to a device rather 
than to a named file. 

• The Operating System detected that the 
UNCATAL0G$0 EJECT system call was not 
incorporated into your system during the 
configuration process. 

E$CONTINUED The Operating System detected a continuation 

character while scanning the command line pointed 
to by the line$p parameter. This condition should 
occur if the command line is to continue on the 
next line. 

E$CONTROL$C The user typed CONTROL-C while the command was 

being loaded. 

E$DEVFD Your task forced the Extended I/O System to attempt 

the physical attachment of a device that had 
formerly been only logically attached. In the 
process of attempting to physically attach the 
device, the Extended I/O System found that the 
device and the device driver specified in the 
logical attachment were inconq>atible. The 
Operating System would not have returned this 
exception code if the device referenced by the 
llne$p parameter had been properly configured in 
the Extended I/O and/or Basic I/O subsystems. 

E$EOF The Application Loader returned this exception code 

because the it encountered an unexpected end of 
file on the object file represented by the 
command -pathname. 


6-40 


C$SEND$COMMAND 


EXCEPTION CODES 
E$EXIST 

E$FACCESS 

E$FIXUP 


E$FLUSHING 

E$FNEXIST 


E$FTYPE 


E$ILLVOL 


(continued) 

The Operating System detached the device containing 
the object file represented by the command-pathname 
before it completed the loading operation. 

The Operating System detected the user as not 
having READ access to the object file represented 
by the command-pathname. 

When the Application Loader load an LTL program, 
the Loader must adjust some of the addresses used 
in the code to reflect actual loaded code 
addresses. This adjustment is known as a fixup and 
is contained on a fixup record. The Application 
Loader subsystem detected an invalid fixup record 
on the object file represented by the 
command-pathname. Refer to the IRMX 86 LOADER 
REFERENCE MANUAL for an explanation of Load-time 
Locatable Code (LTL). 

The Operating System detected the device containing 
the object file represented by the command-pathname 
was in the process of being detached. 

Some file in the command-pathname is either marked 
for deletion or does not exist. For example, the 
pathname A/B/C assumes that A and B are names for 
directories and C is the name of an object file. 
This exception code would have been returned if A, 
B, or C was marked for deletion or did not exist. 

The Operating System detected an error in the 
command-pathname. The pathname included the name 
of a data file as a directory. For example, the 
pathname A/B/C assumes that A and B are names for 
directories. This exception code would have been 
returned if either A or B was something other than 
a directory. 

Your task forced the Extended I/O System to attempt 
the physical attachment of a device that had 
formerly been only logically attached. In the 
process of attempting to physically attach the 
device, the Extended I/O System examined the volume 
label and found that the volume does not contain 
named files. This prevented the Extended I/O 
System from completing physical attachment because 
the named file driver was requested during logical 
attachment. 


C$SEND$COMMAND 


EXCEPTION CODES 
E$IO 

E$IOMEM 

E$JOB$PARAM 


E$JOB$SIZE 


E$LIMIT 


(continued) 

The Operating System detected an I/O error as it 
tried to load the object file represented by the 
command-Tiathname . 

The Basic I/O subsystem job does not currently have 
a block of memory large enough to allow the Human 
Interface to create the connection necessary to 
allow this call to run to completion. 

During the process of configuring the Human 
Interface subsystem, someone modified either the 
MIN$MEMORY or MAX$MEMORY parameters in the Human 
Interface configuration. While processing your 
task, the Operating System detected that the 
MAX$MEMORY parameter is both nonzero and smaller 
than the MIN$MEMORY. 

During the process of configuring the Human 
Interface subsystem, someone modified either the 
MIN$MEMORY or MAX$MEMORY parameters of the Human 
Interface configuration. While processing your 
task, the Operating System detected that the 
MAX$MEMORY parameter is nonzero and too small for 
the object file represented by the command-pathname 
to be loaded. 

When your task Invoked this system call, the call 
invoked at least one other system call. While the 
Operating System performed the latter call, one of 
the following situations occurred. 

• The Human Interface subsystem created enough 
objects to exceed the object limit of the Basic 
I/O System job. Refer to the chapter of the 
iRMX 86 CONFIGURATION GUIDE that discusses the 
Basic I/O System. 

• While creating the objects needed by this call, 
the Operating System detected the calling 
task's job already having reached the maximum 
number of objects that can exist simultaneously. 

• During the process of configuring your 
application system, the Basic I/O System job 
was configured a maximum priority that is too 
low. Specifically, the BIOS maximum priority 
is lower than either the DUIB priority or the 
DEVINFO priority. Refer to the iRMX 86 
CONFIGURATION GUIDE for information regarding 
the BIOS maximum priority. Refer to the GUIDE 
TO WRITING DEVICE DRIVERS FOR THE iRMX 86 AND 
IRMX 88 I/O SYSTEMS for additional information 
regarding the DUIB and DEVINFO. 
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EXCEPTION CODES 

E$LIMIT (continued) 

• The job containing the task which Invoked this 
call, or the job's default user object, is 
currently involved in more than 255 (decimal) 
I/O operations. 

• The calling job's object directory is full or 
the object directory of the created command's 
job is full. 

• The job containing the task which Invoked this 
call was not created by the Human Interface 
subsystem. 

• A value that specified the priority of the 
loaded task in the new job is greater than the 
newly created I/O job's maximum priority. This 
maximum priority was specified during the 
configuration of the Human Interface 
subsystem. Refer to the iRMX 86 CONFIGURATION 
GUIDE for more information. 

• The object directory of the newly created I/O 
job is full. The size of this object directory 
was specified during the configuration of the 
Extended I/O System. Refer to the iRMX 86 
CONFIGURATION GUIDE for more Information. 

• Either the newly created I/O job, or its 
default user, is currently involved in more 
than 255 (decimal) I/O operations. 

E$LITERAL The Operating System detected a literal (quoted 

string) with no closing quote while scanning the 
contents of the command line pointed to by the 
line$p parameter. 

E$LOADER$ SUPPORT The object file represented by the command-pathname 

required capabilities not configured into the 
Application Loader. For example, you might be 
attempting to load PIC code with a loader 
configured only for absolute code. Refer to 
iRMX 86 LOADER REFERENCE MANUAL for an explanation 
of PIC code. 

The command-pathname specified in the line$p 
parameter contains an explicit logical name but the 
Extended I/O System was unable to find this name in 
the object directories of the local job, the global 
job, and the root job. 


E$LOG$NAME 

$NEXIST 


6-43 


C$SEND$COMMAND 


EXCEPTION CODES (continued) 

E$MEDIA The device containing the object file represented 

by the command-pathname was not online. 

E$MEM When your task invoked this call, the call invoked 

at least one other system call. While the 
Operating System performed the latter call, one of 
the following situations occurred. 

• The Operating System detected the memory pool 
of the calling task’s job as not currently 
having a block of memory large enough to allow 
this system call to run to completion. 

• The Operating System detected that the memory 
pool of the newly created I/O job does not 
currently have a block of memory large enough 
to allow the initial task to start running. 

• The Operating System detected that the memory 
pool of the Basic I/O System job does not 
currently have a block of memory large enough 
to allow the Application Loader to run. 

E$NO$LOADER$MEM When your task invoked this system call, the call 

invoked at least one other system call. The latter 
call was a system call of the Application Loader. 
While attempting to perform the Application Loader 
system call, one of the following situations 
occurred. 

• The Operating System detected the memory pool 
of the newly created I/O job as not currently 
having a block of memory large enough to allow 
the Loader to run. 

• The Operating System detected the memory pool 
of the Basic I/O System's job as not currently 
having a block of memory large enough to allow 
the Application Loader to run. 

E$NO$MEM The Application Loader attempted to load PIC or LTL 

groups or segments. However, the memory pool of 
the newly created I/O job does not currently 
contain a block of memory large enough to 
accommodate these groups or segments. Refer to the 
IRMX 86 LOADER REFERENCE MANUAL for an explanation 
of loading PIC or LTL groups or segments. 
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EXCEPTION CODES (continued) 


E$NO$PREFIX The command-pathname specified in the line$p 

parameter of this call contained no explicit prefix 
(no logical name), so the Extended I/O System 
attempted to use the default prefix. However, the 
default prefix is either undefined, or it is not a 
valid device connection or file connection. 

E$NO$ START The object file represented by the command-pathname 

does not specify the entry point for the program 
being loaded. 

E$NOT$CONFIGURED One or more of the following system calls were not 

incorporated during system configuration: 


Call 

Subsystem 

A$ATTACH$FILE 

Basic I/O 

A$CLOSE 

Basic I/O 

A$LOAD$IO$JOB 

Application Loader 

A$OPEN 

Basic I/O 

A$PHYSICAL$ATTACH$DEVICE 

Basic I/O 

A$READ 

Basic I/O 

A$SEEK 

Basic I/O 

A$ SPECIAL 

Basic I/O 

CATAL0G$0 EJECT 

Nucleus 

CREATE$COMPOSITE 

Nucleus 

CREATE $10$ JOB 

Extended I/O 

CREATE$MAILBOX 

Nucleus 

CREATE$SEGMENT 

Nucleus 

CREATE$TASK 

Nucleus 

DELETE $C0MP0SITE 

Nucleus 

DELETE$TASK 

Nucleus 

DISABLE$DELETION 

Nucleus 

ENABLE$DELETION 

Nucleus 

EXIT $10$ JOB 

Extended I/O 

GET$DEFAULT$PREFIX 

Basic I/O 

GET$TYPE 

Nucleus 

L00KUP$0BJECT 

Nucleus 

RECEIVE$CONTROL 

Nucleus 

RECEIVE$MESSAGE 

Nucleus 

S$ATTACH$FILE 

Extended I/O 

S$CATAL0G$C0NNECTI0N 

Extended I/O 

SEND$C0NTR0L 

Nucleus 

SEND$MESSAGE 

Nucleus 

SET$INTERRUPT 

Nucleus 

UNCATALOG$OBJECT 

Nucleus 

WAIT$INTERRUPT 

Nucleus 


E$NOT$PREFIX The Operating System detected the command-pathname 

specified in the line$p parameter containing a 
logical name. The logical name referred to an 
object that was neither a device connection nor a 
file connection. 
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EXCEPTION CODES (continued) 


E$NO$USER The Operating System detected the calling task’s 

job as not having a default user or detected the 
default user of the calling task's job as not being 
a user object* 


E$PARAM When your task invoked this system call, the call 

invoked at least one other system call. While the 
Operating System performed the latter call, one of 
the following situations occurred. 

• The Operating System detected the 
command-pathname referenced in the line$p 
parameter containing a logical name that was 
either longer than 12 characters or contained 
invalid characters. 

• Your task forced the Extended I/O System to 
attempt the physcial attachment of a device 
referenced by the command-pathname in the 
line$p parameter. This device had formerly 
been only logically attached. In the process 
of attempting to physically attach the device, 
the Extended I/O System found that the logical 
attachment referred to a file driver (named, 
physical, or stream) that is not configured 
into your system. Hence the physical 
attachment is not possible. 

• The Operating System detected that the object 
file represented by the command-pathname has a 
stack smaller than 16 bytes. 

E$PARSE$TABLES The Human Interface subsystem has detected an error 

that should not occur unless someone alters an 
internal table used by this subsystem. 

E$PREFIX$SYNTAX The Operating System detected a colon (:) at the 

beginning of the command-pathname specified in the 
line$p parameter, which Indicates that the pathname 
contains a logical name. The Extended I/O System, 
however, was unable to find a second colon to 
terminate the logical name. 


E$REC$FORMAT The Operating System detected that at least one 

record in the object file represented by the 
command-pathname contains a format error. 


E$REC$LENGTH The object file represented by the command-pathname 

contains a record that is longer than the Loader’s 
maximum record length. The Loader’s maximum record 
length is a parameter specified during the 
configuration of the Loader. Refer to the iRMX 86 
CONFIGURATION GUIDE for details. 
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EXCEPTION CODES (continued) 


E$REC$TYPE 


E$ SEPARATOR 


E$SHARE 


E$ STRING 


The Application Loader detected one of the 
following situations while attempting to load the 
object file represented by the command-pathname. 

• At least one record in the file being loaded is 
of a type that the Loader cannot process. 

• The Loader has encountered records in a 
sequence that it cannot process. 

The Operating System detected a command separator 
in while scanning the command line pointed to by 
the line$p parameter. The following is a list of 
the command separators: X, <>, ||, |, [, and ]. 

An Application Loader system call was attempting to 
use the object file represented by the 
command-pathname that is already being used by some 
other task. However, the Application Loader was 
unable to share the file. 

The size of the command-pathname specified in the 
line$p parameter exceeds the length limit of 255 
(decimal) characters. 


E$STRING$ BUFFER The size of the command-pathname specified in the 

line$p parameter exceeds the size of the command 
name buffer that someone specified during the 
configuration of the Human Interface. 

E$TIME Your task was not within a job created by the Human 

Interface subsystem. 


E$TYPE The Operating System detected a command connection 

parameter that refers to an object that is not a 
command connection. 
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C$SEND$CO$RESPONSE 

C$SEND$CO$RESPONSE, a message processing call, sends a message to ;C0: 
and reads a response from :CI: that was defined at the time the job was 
created. 


CALL RQ$C$SEND$CO$RESPONSE(response$p , response$max, message$p, 

except $ptr ) ; 


INPUT PARAMETERS 

message$p A POINTER to a STRING containing the message to be 

sent to :C0:. 

response$max A WORD that specifies the maximum number of 

characters that the response$p string entry may 
contain. If response$max is zero, no response from 
:CI: will be requested and control will return to 
the caller immediately. 


OUTPUT PARAMETERS 

response$p A POINTER to a buffer that will receive a STRING 

containing the user’s response from :CI:. 

except$ptr A POINTER to a WORD in which the Human Interface 

will return an exception code. 


DESCRIPTION 


If a user response is requested to a C$SEND$CO$RESPONSE message, no other 
output will be displayed until the user enters a line terminator from a 
program or console keyboard. If response$p or response$max is zero, the 
Human Interface will not wait for input. If response$p and response$max 
are non-zero, the user may choose to ignore the displayed message by 
entering a line terminator only. The values contained in message$p and 
response$max have the following meaning: 


message$p 


response $max 


Action 


zero 

zero 

non-zero 

non-zero 


zero 

non-zero 

non-zero 

zero 


No I/O will be performed 
Send no message; wait for input 
Send message, wait for input 
Send message, don’t wait 
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DESCRIPTION (continued) 

The main distinction between C$SEND$CO$RESPONSE and C$SEND$EO$RESPONSE 
calls is that the messages sent by C$SEND$EO$RESPONSE are always directed 
to the user’s console screen and cannot be redirected to another device. 
In contrast, messages output by C$SEND$CO$RESPONSE can be redirected via 
a SUBMIT command. 


EXCEPTION CODES 
E$OK 

E$CONTEXT 


E$IO 

E$LIMIT 


No exceptional conditions were encountered. 

When your task invoked this system call, the call 
invoked at least one other system call. While the 
Operating System performed the latter call, one of 
the following situations occurred. 

• The Operating System detected a zero value for 
the object directory size. This indicated that 
your task used a Human Interface call but was 
not within a job created by the Human Interface 
subsystem. 

• While reading from a file to a buffer, the 
connection to the file was not open for reading 
or for both reading and writing. 

• While reading from a file to a buffer, the 
connection to the file was closed. 

• While creating the command connection that 
created the calling task’s job, the Cl and CO 
connections were opened with A$OPEN rather than 
S$OPEN. 

The Operating System detected an I/O error during 
the reading or writing operation. 

When your task Invoked this system call, the call 
invoked at least one other system call. While the 
Operating System performed the latter call, one of 
the following situations occurred. 

• While creating the objects needed by this call, 
the Operating System detected the calling 
task’s job having already reached the maximum 
number of objects that can exist simultaneously. 

• The job containing the task which invoked this 
call, or the job’s default user object, is 
currently involved in more than 255 (decimal) 

I/O operations. 
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EXCEPTION CODES 

E$LIMIT (continued) 

• The job containing the task which invoked this 
call was not created by the Human Interface 
subsystem. 

E$MEM The memory pool of the job containing the task 

which invoked this call does not currently have 
block of memory large enough to allow this system 
call to run to completion. 

E$NOT$CONFIGURED One or more of the following system calls were not 

incorporated during system configuration; 


Call 

Subsystem 

A$READ 

Basic I/O 

A$SEEK 

Basic I/O 

A$WRITE 

Basic I/O 

CREATE$MAILBOX 

Nucleus 

CREATE $SE(^NT 

Nucleus 

DISABLE$DELETION 

Nucleus 

ENABLE$DELETION 

Nucleus 

CET$TYPE 

Nucleus 

LOOKUP $0BJECT 

Nucleus 

RECE I VE$ CONTROL 

Nucleus 

RECEIVE$MESSAGE 

Nucleus 

SEND$ CONTROL 

Nucleus 

SEND$MESSAGE 

Nucleus 

S$READ$MOVE 

Extended I/O 

S$WRITE$MOVE 

Extended I/O 


E$PARAM While processing a write call, the Operating System 

detected an attempt to write beyond the end of a 
physical file. 

E$SPACE While processing a write call, the Operating System 

detected a full volume. The Extended I/O System, 
however, was unable to complete the requested 
writing operation. 

E$TIME Your task was not within a job created by the Human 

Interface subsystem. 
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C $SEND$EO$RESPONSE 


C$SEND$EO$RESPONSE, a message processing call, sends an exceptional 
condition message to the user’s console screen and optionally reads a 
response from the console keyboard. 


CALL RQ$C$SEND$EO$RESPONSE(response$p , response$max, message$p, 

except $ptr ) ; 


INPUT PARAMETERS 

message$p A POINTER to a STRING containing the message to be 

sent to the user’s console screen. If zero, no 
message is sent. 

response$max A WORD that gives the maximum number of characters 

that the response$p entry may contain. If 
response$max is zero, no response from the user’s 
keyboard will be requested and control will return 
to the caller Immediately. 


OUTPUT PARAMETERS 

response$p A POINTER to a buffer that receives the STRING 

containing the user’s response from the console 
keyboard. 

except$ptr A POINTER to a WORD in which the Human Interface 

will return an exception code. 


DESCRIPTION 


After C$SEND$EO$RESPONSE has sent a message to the console screen, no 
other output will be displayed on the screen between the time the message 
is displayed and a line terminator is typed on the console keyboard. The 
values contained in message$p and response$max have the following meaning: 



Action 


zero 

zero 

non-zero 

non-zero 


zero No I/O will be performed 

non-zero Send no message; wait for input 

non-zero Send message, wait for input 

zero Send message, don’t wait 
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G$SEND$EO$RESPONSE 


DESCRIPTION (continued) 

The main distinction between the C$SEND$EO$RESPONSE and C$SEND$CO$RESPOSE 
calls is that the messages output by C$SEND$EO$RESPONSE are always sent to 
the user’s console screen and cannot be redirected to another device. In 
contrast, messages output by C$SEND$CO$RESPONSE can be redirected via a 
SUBMIT command. 


EXCEPTION CODES 
E$OK 

E$CONTEXT 


E$IO 

E$LIMIT 


No exceptional conditions were encountered. 

When your task invoked this system call, the call 
invoked at least one other system call. While the 
Operating System performed the latter call, one of 
the following situations occurred. 

• The Operating System detected a zero value for 
the object directory size. This indicated that 
your task used a Human Interface call but was 
not within a job created by the Human Interface 
subsystem. 

• The connection to the file was not open for 
reading or for both reading and writing. 

• While reading from a file to a buffer or writing 
from a buffer to a file, the connection to the 
file was closed. 

• While creating the command connection that 
created the calling task's job, the Cl and CO 
connections were opened with A$OPEN rather than 
S$OPEN. 

In performing a read or write operation, the 
Operating System detected an I/O error. 

When your task invoked this system call, the call 
invoked at least one other system call. While the 
Operating System performed the latter call invoked, 
one of the following situations occurred. 

• While creating the objects needed by this call, 
the Operating System detected the calling task's 
job having already reached the maximum number of 
objects that can exist simultaneously. 

• The job containing the task which invoked this 
call, or the job's default user object, is 
currently involved in more than 255 (decimal) 

I/O operations. 
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C$SEND$EO$RESPONSE 


EXCEPTION CODES 

E$LIMIT (continued) 

• The job containing the task which invoked this 
call was not created by the Human Interface 
subsystem* 

E$MEM The memory pool of the calling task's job as not 

currently having a block of memory large enough to 
allow this system call to run to completion. 

E$NOT$CONFIGURED One or more of the following system calls were not 

incorporated during system configuration; 


Call 

Subsystem 

A$READ 

Basic I/O 

A$SEEK 

Basic I/O 

A$WRITE 

Basic I/O 

CREATE$MAILBOX 

Nucleus 

CREATE $SEGMENT 

Nucleus 

DISABLE$DELETION 

Nucleus 

ENABLE$DELETION 

Nucleus 

CET$TYPE 

Nucleus 

LOOKUP$OBJECT 

Nucleus 

RECEIVE$CONTROL 

Nucleus 

RECEIVE$MESSACE 

Nucleus 

SEND$CONTROL 

Nucleus 

SEND$MESSACE 

Nucleus 

S$READ$MOVE 

Extended I/O 

S$WRITE$MOVE 

Extended 


E$PARAM While trying to write to the output, the Operating 

System detected an atten5>t to write beyond the end 
of a physical file* 

E$SPACE While trying to write to the output, che Operating 

System detected a full volume. Due to this 
condition, the requested writing operation has not 
been conq)leted. 

E$TIME Your task used a Human Interface call but was not 

within a job created by the Human Interface 
subsystem. 
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C$SET$CONTROL$C 


C$SET$CONTROL$C 

C$SET$CONTROL$C , a program control call, changes a calling program’s 
CONTROL C exchange to the semaphore specified in the C$SET$CONTROL$C call. 


CALL RQ$C$SET$CONTROL$C(control$c$semaphore, except$ptr); 


INPUT PARAMETER 

control$c$semaphore A WORD containing the TOKEN for the user's 

semaphore to which a single unit will be sent when 
a CTRL/c is typed on the console keyboard. If the 
control$c$seraaphore TOKEN is zero, the program's 
default CONTROL C semaphore will receive any future 
CONTROL C units. 


OUTPUT PARAMETER 

except$ptr A POINTER to a WORD in which the Human Interface 

will return an exception code. 


DESCRIPTION 

This call lets you modify the "standard" response to a CTRL/c entry to a 
response that is appropriate for the given command. The default action 
is to delete the command entry. 

One unit will be sent to the semaphore each time CTRL/c is typed. 

Any units sent to the semaphore that exceeds the maximum number specified 
during system configuration will be Ignored. 


EXCEPTION CODES 

E$OK No exceptional conditions were encountered. 

E$CONTEXT When your task invoked this system call, the 

Operating System detected a zero value for the 
object directory size. This indicated that your 
task used a Human Interface call but was not within 
a job created by the Human Interface subsystem. 

The other possibility is that RQ$UNCATALOG$OBJECT 
was not configured. 

E$NOT$CONFIGURED The Nucleus System call CATALOG$OBJECT was not 

incorporated during system configuration. 
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C$SET$CONTROL$C 


EXCEPTION CODES 
E$LIMIT 

E$TYPE 


(continued) 

When your task Invoked this system call, the 
Operating System detected an object directory that 
had already reached the maximum object directory 
size* 

The TOKEN given in the parameter 

control$c$semaphore is not a TOKEN for a semaphore. 
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C$SET$PARSE$BUFFER 


C$SET$PARSE$BUFFER 


C$SET$PARSE$BUFFER, a connnand parsing call, permits parsing the contents 
of a buffer other than the command line buffer whenever the parsing calls 
are used. 


offset = RQ$C$SET$PARSE$BUFFER(buf f $p , buff$max, except$ptr); 


INPUT PARAMETERS 
buf f $p 


buf f $max 


A POINTER to a STRING containing the text to be 
parsed. If the buff$p is zero, the buffer used for 
parsing reverts to the command line buffer and the 
buff$max parameter is ignored. 

A WORD that specifies the number of characters in 
the buffer that are to be used in parsing. 


OUTPUT PARAMETERS 

offset A WORD that receives the byte offset, in the 

previous buffer, of the last byte parsed by the 
Human Interface library calls. 

except$ptr A POINTER to a WORD in which the Human Interface 

will return an exception code. 


DESCRIPTION 

The user may change buffers and revert back to the command line parsing 
buffer at will, by calling C$SET$PARSE$BUFFER with buff$p=0. However, 
only one parsing buffer per job may be active at any given time. 

Note that C$SET$PARSE$BUFFER does not affect C$GET$INPUT$ PATHNAME or 
C$GET$OUTPUT$PATHNAME calls; that is, C$SET$PARSE$BUFFER does not 
redirect these calls* input source. 


EXCEPTION CODES 

E$OK No exceptional conditions were encountered. 
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C$SET$PARSE$BUFFER 


EXCEPTION CODES (continued) 

E$CONTEXT When your task Invoked this system call, the 

Operating System detected a zero value for the 
object directory size. This indicated that your 
task was not within a job created by the Human 
Interface subsystem. 

E$LIMIT While processing this calling jobs object 

directory, the Operating System detected an object 
directory that has already reached the maximum 
object directory size. 

E$NOT$CONFIGURED The Nucleus System call LOOKUP$OBJECT was not 

incorporated during system configuration. 

E$TIME Your task was not within a job created by the Human 

Interface subsystem. 
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CHAPTER 7. COMMAND CREATION EXAMPLES 


The examples provided in this chapter are intended to provide some 
insight as to how and why Human Interface system calls are used to 
perform command parsing and processing in user-designed programs. The 
examples presented in following pages are not complete programs and are 
not tested. Therefore, they should be used only for general guidance 
when preparing your own commands. 


EXAMPLE 1. STANDARD SYSTEM CALLS 

Shoxv's implementation of the following "standard" Human Interface system 
calls: 


C$GET$INPUT$PATHNAME 
C $GE T $OUTPUT $P ATHNAME 
C$GET$INPUT$CONNECTION 
C$GET$OUTPUT$CONNECTION 


EXAMPLE 2. PARSING CALL 

Shows implementation of the following Human Interface parsing call: 
C$GET$PARAMETER 


EXAMPLE 3. ADVANCED SYSTEM CALLS 


Show in^) lamentation of the folloxi/ing "advanced" Human Interface system 
calls: 


C $ C RE ATE $ C OMMAND$ C ONNE CT ION 

C$SEND$COMMAND 

C$DELETE$COMMAND$CONNECTION 
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COMMAND CREATION EXAMPLES 


EXAMPLE 1. STANDARD SYSTEM CALLS 


* This example demonstrates the use of the following Human Interface * 

* standard input and output functions. * 

ic ie 


rq$C$get$input$pathname 

rq$G$get$output$pathnaine 

rq$C$get$intput$connection 

rq$C$get$output$connection 


* This program is a possible implementation of a copy utility, the * 

* purpose of which is to copy data from successive input files to the * 

* corresponding successive output files. For example, to copy file A * 

* to file B, file C to file D, and file E to file F, we could specify * 

* in a command line: * 

* COPY A,C,E TO B,D,F * 

* * 




copy: DO; 

DECLARE (input$pathname , output$pathname) structure ( 

length byte, 
string (41) byte ) , 

output$prep byte, 

(input$token , output! token) word, 
status word; 

/* Get the 1st input pathname string */ 

CALL rq$C$get$input$pathname (0input$pathname , SIZE (inputSpathname) , 0status) ; 

DO WHILE (input$pathname . length <> 0); /* A zero length indicates no more 

input parameters. */ 

/* Get the corresponding output pathname string */ 
output$prep = rq$C$get$output$pathname (0output$pathname , 

SIZE (output$pathname) , 0(7, 'TO :C0:'), 
0status) ; 


/* Establish connection with next pair of input and output files */ 

input$token = rq$C$get$input$connnection (0input$pathname , 0status) ; 

outputStoken = rq$C!get!output$connection (0output$pathname , 

outputSprep, 0status) ; 


. Copy data and close both files. 


/* Get the next input pathname string */ 

CALL rq$C$get$input$pathname (0input$pathname, SIZE (input$pathname) , @status) 
END /* DO WHILE */; 

END copy; 
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COMMAND CREATION EXAMPLES 


EXAMPLE 2. PARSING CALL 


* * 


This example demonstrates the use of the following Human Interface 
parse standard function: 

rq$C$get$ parameter 

This program makes use of the get$parameter primative to parse out a 
keyword parameter in a command line. Here, the keyword, "SIZE”, is 
parsed out, and its value-part converted to a word value and placed 
"size$val". For example, we could specify in a command line: 


PROGl 


SIZE = 400 


Note that if the "SIZE" parameter is not present, "size$val" receives 
a default value. 


•klclfk-k-kltle'iciiltli'kitlt-ic'ftic-k-klc-k-kli'tilt-kiclcic-k-kifk-kmiicif-k-iili-kii'icltiiiticlt-fi-kiticificlcltli-iiltli-k-k'iilcltlilcifkls'kiilfky 

progl: DO; 

DECLARE STRING LITERALLY 'STRUCTURE (len BYTE, str (1) BYTE)', 

STRING$TABLE LITERALLY 'STRUCTURE (num$entries BYTE, 

entries (1 ) BYTE) ' , 
PARAMETER$KEYWORD$MAX LITERALLY '20', 

VALUE$TABLE$MAX LITERALLY '80', 

DEFAULT$SIZE LITERALLY '100'; 

DECLARE val ue$ table$ buf ( VALUE$TABLE$MAX ) BYTE, /* Receives value string tbl.*/ 
value$table STRING$TABLE AT (0value$ table$ buf ) , 
value$ str$ptr POINTER, 

value$str based val ue$ st r$ptr STRING, /* For referencing strings 

within the string table */ 

parameter$keyword$buf (PARAMETER$KEYWORD$MAX ) BYTE, /* Receives the 

keyword string*/ 

parameter$keyword STRING AT (@parameter$keyword$buf ) , 

predict$list (*) BYTE DATA ( 2 , 2 , ' TO ' , 5 , ' AFTER ' ) , /* Sample predict 

list table */ 

pred ict$ 1 ist$ index BYTE, /* Receives prep, string displacement within 

pred ic t$ 1 i St , if a preposition is present*/ 

status WORD, 

(size$val, i) WORD; 

/* Get the next parameter, if present */ 

IF ( rq$c$get$parameter ( 0parameter$keyword , PARAMETER$KEYWORD$MAX , 

0value$ table, VALUE$TABLE$MAX , 

@predict$list$ index, @predict$list, 

©status ) ) THEN 

IF (parameter$keyword. str (0 ) = 'S') AND /* Is the keyword 'SIZE' ? */ 
(parameter$keyword.str (1 ) = '!') THEN 
DO; 

val ue$ St r$ pt r = 0value$ table. entries; /* Point to 1st entry in table */ 
size$val = 0; 

DO i = 0 to value$ str . len - 1; /* Convert number string to a word value */ 
size$val = size$val * 10; 

size$val = size$val + ( val ue$ str . str { i ) - 30H); 

END; 

END; 

ELSE 

size$val = DEFAULT$SIZE; /* If the 'SIZE' parameter is not present, 

use the default size. */ 


Rest of program 


END progl; 
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COMMAND CREATION EXAMPLES 
EXAMPLE 3. ADVANCED SYSTEM CALLS 




* * 

* This example demonstrates the use of the following Human Interface * 

* advanced stancJard functions: * 

* * 

* rq$C$cre.ate$command$connection * 

* rq$C$send$command * 

* rq$C$delote$ commands connect ion * 

* * 


* This program uses the above functions to invoke a copy utility * 

* from within, and then continue normal processing. The program is * 

* invoked by the command line: * 

* PROG2 * 

* * 

**************************************************************************** ^ 


prog 2: DO; 


DECLARE (ciStoken, coStoken, commandSconnectionS token) WORD, 
(status, statusl) WORD; 


/* INVOKE UTILITY TO COPY FILE OLD TO FILE NEW */ 

/* Get tokens for Cl and CO */ 

ciStoken = rqS cSgetS inputS connec t ion ( @ (4 , ' : C I : ' ) , ^status) ; 
coStoken = rqS cSgetSoutputS connect ion ( @ (4 ,': CO: ') , ^status) ; 

/* Create command connection */ 

commandSconnectionS tok = rqScScreateScommandSconnection (ciStoken, 

coS token , 

0 , 

©status ) ; 

/* Send command to copy files */ 

CALL rqS cS sends command (commands connect ionS tok , 

@(23, 'COPY :F1:0LD TO :F1:NEW'), 

@statusl, ©status); 

/* Delete command connection */ 

CALL rqScSdeleteScommandSconnection ( commands connect ionS tok , ©status); 


. Rest of program 


END prog 2; 
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APPENDIX A. HUMAN INTERFACE TYPE DEFINITIONS 


The type definitions used in Human Interface system call description are 
defined in Table A-1. 


Table A-1. Type Definitions 


Type 

Definition 

BYTE 

PL/M 86 data type (8 bits). 

WORD 

PL/M 86 data type (16 bits). 

POINTER 

PL/M 86 data type (32 bits). 

STRING 

A sequence of bytes, the first of which contains the number 
of bytes in the sequence, (not including the count byte). 
Since the count is only a byte, the maximum number of 
characters that a STRING may contain is 255 characters. A 
zero length specifies a null string. 

TOKEN 

A 2-byte iRMX 86 variable that contains the means of 
locating an object. 







APPENDIX B. HUMAN INTERFACE EXCEPTION CODES 


Like other IRMX 86 software systems, the Human Interface returns a 
condition code whenever a Human Interface call is invoked. If the call 
executes without error, the Human Interface returns the code E$OK. When 
an error is encountered during call execution, an exceptional condition 
code is returned. The exceptional condition code may be returned either 
from the Human Interface or from one of the other iRMX 86 systems 
residing below it. 

The exception codes listed in Table B-1 are unique to the Human Interface. 


Table B-1. Human Interface Exception Codes 


Programmer Errors: 


E$PARSE$TABLES: 8080h 

E$DEFAULT$SO: 808 3h 

E$STRING; 8084h 


Environmental Errors 



E$0K: OOOOh 

E$LITERAL: 0080h 

E$STRING$BUFFER: 0081h 

E$SEPARAT0R: 0082h 

E$C0NTINUED; 0083h 
E$LIST: 0085h 

E$PREP0SITI0N; 0087h 
E$PATH: 0088h 

E$C0NTR0L$C: 0089h 

E$C0NTR0L: 008Ah 

E$EXTRA$S0 008Bh 







HUMAN INTERFACE EXCEPTION CODES 


Other exception codes may be issued during Human Interface operations. 
The hexadecimal values of these exception conditions fall into ranges 
based on the subsystem which first detects the condition. Table B-2 
lists the subsystems and their respective ranges. 


Table B~2. Exception Code Ranges 


- - - — — 

System 

Environmental 

Programming 

Nucleus 

0 to IFH 

8000 to 801FH 

Basic I/O System 

20 to 3FH 

8020 to 803FH 

Extended I/O System 

40 to 5FH 

8040 to 805FH 

Application Loader 

60 to 7FH 

8060 to 807FH 

Human Interface 

80 to AFH 

8080 to 80AFH 

Universal Development 

CO to DFH 

80C0 to 80DFH 

Interface 



Reserved * 

130 to 14FH 

8130 to 814FH 

* Exception codes in this range 

could occur if you are a user of an 

iRMX system with MMX software 

. Refer to iMMX 

800 SOFTWARE REFERENCE 

MANUAL AND USER'S GUIDE for an explanation of 

exception conditions 

within this range. 










HUMAN INTERFACE EXCEPTION CODES 


Table B-2 provides a minimum of information about an exception 
condition. In most cases, the exception condition must be considered in 
terms of the unique circumstances that caused the condition. Table B“3 
is provided to guide you to the most appropriate manual. The appropriate 
iRMX 86 manuals have more detailed descriptions of the meanings. The 
appropriate manual is listed in the column marked "Manuals”. 


Table B-3. iRMX 86* Condition Codes 


Hex. 

Value 

Mnemonic 

Manuals 
N B E L H 

Meaning 

OH 

E$OK 

* * 

k k k 

No exceptional conditions (normal) 

Environmental Conditions 


IH 

E$TIME 

* * 

k k k 

A time limit (possibly a limit of 
zero time) expired without a task's 
request being satisfied. 


2H 

E$MEM 

* * 

k k k 

Insufficient available memory to 
satisfy a task's request. 


3H 

E$BUSY 

S 


Another task currently has access to 
data protected by a region. 


4H 

E$LIMIT 

■k * 

k k k 

A task attempted an operation which, 
if it had been successful, woiild have 
violated a Nucleus -enforced limit. 


5H 

E$CONTEXT 

■k * 

k k k 

A system call was issued out of 
proper context. 


6H 

E$EXIST 

k k 

k k k 

A token parameter has a value which 
is not the token of an existing 
object. 

N 

B 

E 

Nucleus Reference Manual 
Basic I/O System Ref Manual 
Extended I/O Sys Ref Manual 

L Loader Reference Manual 

H Human Interface Reference Manual 

S System Programmer's Ref Manual 
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HUMAN INTERFACE EXCEPTION CODES 


Table B-3. IRMX 86™ Condition Codes 


Hex. 

Value 

Mnemonic 

Manuals 
N B E L H 

Meaning 

Environmental Conditions (continued) 

7H 

E$STATE 

* 

A task attempted an operation which 




would have caused an impossible 



! 

transition of a task’s state. 

8H 

E$NOT$CON- 

***** 

This system call is not part of the 


FIGURED 

! 


present configuration. 

9H 

E$INTER- 

* 

An interrupt task has accummulated the 


RUPT$SAT- 


maximum allowable amount of 


URATION 


SIGNAL$INTERRUPT requests. 

OAH 

E$ INTER- 

* 

An interrupt task has accummulated 


RUPT$- 


more than the maximum allowable amount 


OVERFLOW 


of SIGNAL$INTERRUPT requests. 

2 OH 

E$FEXIST 

* * 

File already exists. 

21H 

E$FNEXIST 

* * * * 

File does not exist. 

22H 

E$DEVFD 

* * * 

Device and file driver are 




incompatible. 

23H 

E$SUPPORT 

* * * * 

Combination of parameters not 




supported. 

24H 

E$EMPTY$- 

* * 

The specified slot in a directory 


ENTRY 


file is en 5 )ty. 

25H 

E$DIR$END 

* * 

The specified slot is beyond the end 




of a directory file. 

26H 

E$F ACCESS 

:k :k :k :k 

1 

File access not granted. 

27H 

E$FTYPE 

* * * 

Incompatible file type. 

28H 

E$SHARE 

* * * * 

Improper file sharing requested. 

29H 

E$ SPACE 

* * 

No space left. 


N Nucleus Reference Manual L Loader Reference Manual 

B Basic I/O System Ref Manual H Human Interface Reference Manual 

E Extended I/O Sys Ref Manual S System Programmer’s Ref Manual 










HUMAN INTERFACE EXCEPTION CODES 


Table B-3. IRMX 86™ Condition Codes 


Hex. 

Value 

Mnemonic 

Manuals 
N B E L H 

Meaning 


Environmental Conditions (continued) 

2AH 

E$IDDR 

* * 

Invalid device driver request. 

2BH 

E$IO 

* * * * 

An I/O error occured. 

2CH 

E$FLUSHING 

it it it ic 

Connection specified in call was 
deleted before the operation was 
completed. 

2DH 

E$ILLVOL 

s * 

Invalid ly named volume. 

2EH 

E$DEV$OFF- 

LINE 

it 

The device being accessed if now 
offline. 

4 OH 

E$PREFIX$- 

SYNTAX 

* * 

The specified path starts with a colon 
(:) but does not contain a second, 
matching colon. 

41H 

E$CANNOT$- 

CLOSE 

it 

The Extended I/O System was not able 
to transfer remaining data in buffers 
to output device. 

42H 

E$IOMEM 

it it 

The Basic I/O System has insufficient 
memory to process a request. 

44H 

E$MEDIA 

it it 

The device containing a specified 
file is not online. 

45H 

E$LOG$NAME- 

NEXIST 

it it 

The Extended I/O System was unable 
to find a specified logical name in 
the object directories that it checks. 

6 OH 

E$ABS$ADD- 

RESS 

it 

An absolute object program was loaded 
into system protected memory area. 

61H 

E$BAD$GROUP 

it it 

Illegal group component in the a 
group definition record. 

62H 

E$BAD$“ 

HEADER 

it it 

Illegal header record in the object 
file. 

N Nucleus Reference Manual 

L Loader Reference Manual 

B Basic I/O System Ref Manual 

H Human Interface Reference Manual 

E Extended I/O Sys 

Ref Manual 

S System Programmer’s Ref Manual 
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HUMAN INTERFACE EXCEPTION CODES 


Table B-3. iRMX 86 ^ Condition Codes 


Mnemonic 


Manuals 
N B E L H 



Environmental Conditions (continued) 


63H E$BAD$SEG- 

MENT 

64H E$CHECKSUM 


65H E$EOF 

66H E$FIXUP 

67H E$NO$LOADER 

$MEM 

68H E$NO$MEM 

69H E$REC$FMT 

6AH E$REC$- 
LENGTH 

6BH E$REC$TYPE 

6CH E$NO$STi\RT 

6DH E$JOB$S rZE 


6EH E$OVLY 


6FH E$LOADER 
$ SUPPORT 


Illegal segment definition record. 


A checksum error occurred while 
reading an object record. 

Unexpected end of file encountered 
while reading object records. 

Illegal fixup record in the object 
file. 

Insufficient memory to satisfy 
loader dynamic memory requirements. 

Insufficient memory to create PIC/LTL 
segments . 

Illegal record format encountered. 

Record length of an object record 
exceeds configured loader-buffer size. 

Illegal record type encountered in 
the object file. 

Start address not found. 

Maximum job-size specified is less 
than the memory requirement specified 
in the object file. 

Overlay name does not match with any 
of the overlay module names. 

The object file being loaded requires 
features not supported by the 
configured loader. 


N Nucleus Reftirence Manual L Loader Reference Manual 

B Basic I/O System Ref Manual H Human Interface Reference Manual 

E Extended I/O Sys Ref Manual S System Programmer’s Ref Manual 
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HUMAN INTERFACE EXCEPTION CODES 


Table B-3. IRMX 86™ Condition Codes 


Hex. 

Value 

Mnemonic 

Manuals 
N B E L H 

Meaning 

Environmental Conditions (continued) 

8 OH 

E$LITERAL 

* 

The parse buffer contains a literal 
with no closing quote. 

81H 

E$STRING$- 

BUFFER 

* 

The string to be returned as the 
parameter name exceeds the size of 
the buffer the user provided in the 
cal 1 . 

82H 

E$SEPARA- 

TOR 

* 

The parse buffer contains a command 
separator. 

83 

E$CONTINUED 

* 

The parse buffer contains a 
continuation character. 

85H 

E$LIST 

* 

The last value of the value list is 
missing. 

87H 

E$PREPOSI- 

TION 

* 

The same preposition as on the the 
command line was indicated, but can 
not be used. 

89H 

E$CONTROL$C 

* 

The user typed CONTROL-C while the 
command was being loaded. 

8BH 

E$EXTRA$SO 

■k 

There were no more input pathnames 
although the output pathname list was 
not empty. 


Programmer Errors 


8000H 

E$ZERO$- 

* 

A task attempted to divide by zero. 


DIVIDE 



8001H 

E$OVER-FLOW 

* 

An overflow Interrupt occurred. 

8002H 

E$TYPE 

k k k k k 

A token parameter referred to an 
existing object that is not of the 
required type. 
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HUMAN INTERFACE EXCEPTION CODES 


Table B-3. IRMX Sb* Condition Codes 


Hex. 

Value 

Mnemonic 

Manuals 
N B E L H 

Meaning 

Programmer Errors (continued) 

8003H 

E$BOUNDS 

* 

A task attempted to access beyond the 




end of a segment. 

8004H 

E$PARAM 

•k -k ^ ic :k 

A parameter which is neither a token 




nor an offset has an invalid value. 

8005H 

E$BAD$CALL 

k k 

The I/O System code has been damaged. 




probably due to a bug in an 




application task. Recovery is not 




possible. 

8020H 

E$IFDR 

k k 

Invalid file driver request. 

8021H 

E$NOUSER 

k k k 

No default user. 

8022H 

E$NO$PREFIX 

k k k 

No default prefix. 

8040H 

E$NOT$- 

k k 

Specified object is not a device 


PREFIX 


connection or file connection. 

8041H 

E$NOT$- 

k 

A token parameter referred to an 


DEVICE 


existing object that is not, but 




should be, a device connection. 

8042H 

E$NOT$CON- 

* 

A token parameter referred to an 


NECTION 


existing object that is not, but 




should be, a file connection. 

8060H 

E$JOB$PARAM 

k k 

The maximum job-size specified is 




less than the minimum job-size. 

8080H 

E$PARSE$- 

k 

There is an error in the interal 


TABLES 


parse tables. 

8083H 

E$DEFAULT$SO 

k 

The default output name STRING is 




invalid. 

8084H 

E$STRING 

k 

The pathname to be returned exceeds 




255 characters in length. 
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APPENDIX C. STRING TABLE FORMAT 


The string table may be generated by using standard PL/M declarations. 
The diagram in Figure C-1 shows the string$table parameter format. 


BYTE: number of entries (n) 


STRING: string 1 


STRING: string 2 


STRING: string 3 


STRING: string n 


Extra space, if any 


Figure C-1. String Table Format 
See Appendix A for a definition of a STRING. 


EXAMPLE: 

Assume you wish to generate a preposition list for HAPPY, GLAD, and SAD. 
The following declarations would be needed: 

DECLARE 

p$table(*) BYTE DATA(3, /* NUMBER OF STRINGS */ 

(5, ’HAPPY'), 

(4, 'GLAD' ), 

(3, 'SAD'), ); 


C-1 





INDEX 


Underscored entries are primary references. 


$: prefix 

1-6, 1-7, 1-8 




BB: prefix 

1-7, 1-8 




Cl: prefix 

1-3, 1-7, 1-8, 

2-5, 4-2, 

4-6, 

4-10, 6-4, 6-48 

CO: prefix 

r Art 

1-3, 1-7, 1-8, 

2-5, 4-4, 

A-7, 

4-12, 6-4, 6-14, 6-23, 6-31, 


6-48 

:PROG; prefix 1-2, 1-5 , 1-8, 5-7 
: SYSTEM: prefix 1-2, 1-5 , 1-8, 5-7 
:WORK; prefix 1-6 , 1-8 

A$GET$EXTENSION$DATA system call 3-42 
A$SET$EXTENSION$DATA system call 3-42 
absolute load 5-8 
access rights 3-31, 3-51 

AFTER preposition 2-6 , 4-3, 4-6, 4-12, 5-4, 5-7, 6-22, 6-31, 6-51 
ampersand 2-3 
AS preposition 2-7 

ATTACH$FILE 6-6, 6-7, 6-9, 6-15, 6-18, 6-27, 6-28, 6-45 
ATTACHDEVICE command 1-7, 2-7, 3-5, 5-8 

BACKUP command 3-9 , 3-49 
buffer parsing 6-56 
BYTE definition A-1 

C$CR£ATE$COMMAND$ CONNECTION system call 5-5, 6-3, 6-4 , 6-10, 6-38, 7-1 
C$DELETE$COMMAND$CONNECTION system call 5-5, 6-3, 6-4, 6-10, 7-1 
C$FORMAT$EXCEPTION system call 5-8, 6-2, 6-11 
C$GET$CHAR system call 6-2, 6-13 
C$GET$EXCEPTION$ HANDLER system call 5-8 

C$GET$INPUT$CONNECTION system call 5-3, 6-2, 6-14, 6-15, 6-20, 7-1 
G$GET$INPUT$ PATHNAME system call 5-1, 5-3, 6-2, 6-20 , 6-56, 7-1 
C$GET$0UTPUT$C0NNECTI0N system call 5-3, 5-4, 6-2, 6-22, 6-23, 
6-31,6-32, 7-1 

C$GET$OUTPUT$ PATHNAME system call 6-2, 6-29, 6-31 , 6-32, 6-56 
C$GET$PARAMETER system call 5-1, 5-6, 6-2, 6-34 , 6-35, 7-1 
C$SEND$CO$RESPONSE system call 6-2, 6-48 , 6-49, 6-52 
C$SEND$COMMAND system call 5-5, 6-3, 6-4, 6-38 , 6-39, 7-1 
C$SEND$E0$ RESPONSE system call 6-2, 6-49, 6-51 , 6-52 
C$SET$C0NTR0L$C system call 5-5, 5-8, 6-3, 6-54 
C$SET$PARSE$BUFFER system call 6-2, 6-56 
CATAL0G$0 EJECT system call 6-7, 6-45, 6-54 
CLOSE system call 6-45 

Command Line Interpreter 1-1 , 2-3, 5-4, 5-6 


Index- 1 



INDEX 


command 

connection 5-5, 6-3, 6-4 , 6-10 

creation 5-7 

dictionary 3-3 

entry 2-1, 2-4 

exanq)les 4-1 

Human Interface 3-1 

invocation 5-7 , 6-4 


line l-l, 2-2, 

2-8, 4-2, 

4-7, 4-20, 6-2, 6-13, 6-20, 6-22, 6-31, 

6-34, 6-38, 

6-56 


name 1-1, 1-4, 

2-2, 5-2, 

6-47 

parsing 6-2, 6- 

-20, 6-31, 

6-34, 6-56, 7-1 


processing calls 5-5 , 7-1 
syntax 2-1, 3-1 , 2-2 
comment character 2-3 
console 

input device 2-5 
output device 2-5 
session 2-1 

continuation mark 2-3, 6-38 
CONTROL keys 2-7 

COPY command 2-4, 3-15, 4-2, 4-4, 4-6, 4-12, 4-16, 4-20, 4-21 
CREATE$C0MMAND$C0NNECTI0N system call 5-5, 6-3, 6-4, 6-10, 6-38, 7-1 
CREATE$C0MP0SITE system call 6-7, 6-18, 6-27, 6-45 
CREATE$FILE system call 6-7, 6-8, 6-9, 6-27, 6-28 
CREATE$I0$J0B system call 6-45 

CREATE $MAILB0X system call 6-7, 6-18, 6-27, 6-45, 6-50, 6-53 

CREATES SEGMENT system call 6-7, 6-18, 6-21, 6-28, 6-33, 6-45, 6-50, 6-53 

CREATE$TASK system call 6-7, 6-45 

CREATEDIR command 1-5, 1-6, 3-19 , 4-9 

CTRL keys 


CTRL key 2-7 

CTRL/c 

1-4, 2-7, 4-5, 5-5, 5-8, 6-54 

CTRL/d 

2-7 

CTRL/q 

2-7, 4-5 

CTRL/s 

2-7, 4-5 

CTRL/x 

2-7, 4-5 

CTRL/z 

2-7, 4-1, 4-2 


DATE command 3-20 

DEBUG command 3-2 1 

default directory 1-6 , 1-8, 4-13 

default message 6-2, 6-11 

DELETE access 6-23 

DELETE command 3-22, 4-8, 4-10, 4-13 

DELETE$C0MMAND$ CONNECTION system call 5-5, 6-3, 6-4, 6-10, 7-1 
DELETE$C0MP0SITE system call 6-7, 6-18, 6-28, 6-45 
DELETESTASK system call 6-45 
DETACHDEVICE command 3-24 

Device Unit Inforiaatlon Block (DUIB) 3-5 , 3-21, 6-7, 6-17, 6-26, 6-42 
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INDEX 


device 

attachment 3-5 
detachment 3-25 
fnodes 4-18 
granularity 4-18 
Interleave factor 4-18 
logical 
physical 

DIR command 1-5, 2-9, 3-25 , 4-9, 4-12, 4-18, 4-19 

directory 1-4, 1-5, 1-6, 4-2, 4-8, 4-9, 4-10, 4-11, 4-12, 4-13, 4-14, 
4-16, 4-18, "5^9, 5-7 
directory 

creation 3-19 , 4-9 
deletion 3-22, 4-13 
exain)les 3-27 
formats 3-29 
listing 3-25 , 4-12 
parent 4-10 
renaming 3-45 , 4-16 
restoring 3-48 
user default 4-13 

DISABLE$ DELETION system call 6-8, 6-18, 6-28, 6-45, 6-50, 6-53 

diskette switching 4-19 

DISKVERIFY command 3-32 

DOWNCOPY command 3-37 

DUIB 3-5 , 3-21, 6-7, 6-17, 6-26, 6-42 

embedded blanks 2-2, 2-3 

ENABLE$DELETION system call 6-8, 6-18, 6-28, 6-45, 6-50, 6-53 

error input device 6-2 

error messages 2-1 

error output device 6-2 

ESC key 2-2, 2-3, 2-8, 5-1 


exception code 

5-8, 

6-5, 6- 

-10, 6-12, 

6-13, 

6-15, 

6-20, 6-24, 

6-32 

6-39, 6-49, 

6-52 

, 6-54, 

6-56 





exception code 

mnemonics , 






E$C0NTEXT 

6-5, 

6-13, 6- 

-15, 6-21, 

6-24, 

6-32, 

6-35, 6-39, 

6-40 

6-49, 6 

-52, 

6-54, 6- 

-57 






E$C0NTINUED 6-35, 6-38, 6-40 
E$C0NTR0L$C 6-39, 6-40 
E$ DEFAULTS SO 6-32 
E$DEVFD 6-5, 6-16, 6-24, 6-40 
E$EXIST 6-6, 6-41 
E$EXTRA$S0 6-21 

E$FACCESS 6-16, 6-24, 6-25, 6-41 
E$FLUSHING 6-41 
ESFNEXIST 6-16, 6-25, 6-41 
E$FTYPE 6-16, 6-25, 6-41 
E$ILLV0L 6-16, 6-25, 6-41 

E$I0 4-19, 6-6, 6-17, 6-25, 6-42, 6-49, 6-52 
E$I0MEM 6-6, 6-17, 6-25, 6-42 

E$LIMIT 6-6, 6-7, 6-17, 6-21, 6-25, 6-26, 6-32, 6-42, 6-43, 6-49, 
6-50, 6-52, 6-53, 6-55, 6-57 
E$LIST 6-21, 6-32, 6-36 
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INDEX 


exception code mnemonics (continued) 
E$LITERAL 6-36, 6-43 
E$MEDIA 6-17, 6-26, 6-44 


E$MEM 6-7, 6-18, 

6-21, 

6-27, 

6-32, 

6-44, 6-50, 6-53 


E$NO$PREFIX 8-18, 

6-27, 

6-45 





E$NOT$CONFIGURED 

6-7, 6 

-8, 6- 

13. 

6- 

“18, 6-21, 6-27, 6- 

28, 6-33, 

6-36, 6-45, 6- 

50, 6- 

53, 6- 

54, 

6- 

-57 


E$N0T$PREFIX 6-8, 

6-19, 

6-28, 

6- 

45 



E$0K 6-5, 6-LO, 6 

-12, 6 

-13, 6 

-15 

, « 

>-20, 6-24, 6-32, 6 

-35, 6-39 

6-49, 6-52, 6- 

54, 6- 

56 





E$PARAM 4-4, 6-8, 

6-12, 

6-19, 

6- 

28 , 

, 6-29, 6-46, 6-50, 

6-53 

E$PARSE$TABLES 6- 

21, 6- 

33, 6- 

36, 

6- 

■46 


E$PREFIX$SYNTAX 6 

-19, 6 

-29, 6 

-46 





E$PREPOSITION 6-29 
E$SEPARATOR 6-36, 6-47 
E$SHARE 6-19, 6-29, 6-47 

E$STRING 6-12, 6-21, 6-33, 6-36, 6-37, 6-47 
E$STRING$ BUFFER 6-12, 6-21, 6-33, 6-36, 6-37, 6-47 
E$ SUPPORT 6-9, 6-30 

E$TIME 6-9, 6-13, 6-19, 6-21, 6-30, 6-33, 6-37, 6-47, 6-50, 6-53, 
6-57 

E$TYPE 6-9, 6-10, 6-47, 6-55 
Exception handler 5-8 
EXIT$I0$J0B system call 6-45 

Extended I/O System l-l, 1~2, 5-3, 6-5, 6-7, 6-8, 6-14, 6-15, 6-16, 


6-17, 6-18, 6-19, 6-20, 

6-22, 

6-23, 

6-24, 

6-25, 

6-27, 6-28, 6-29, 

6-30, 6-32, 6-40, 6-41, 

6-43, 

6-45, 

6-46, 

6-50, 

6-53 

EXTENDED parameter 2-2 
extension data 3-11, 3-41, 

3-42, 

3-52 





file 

access rights 3-31 
backup 3-8 

concatenation 3-15 , 4-6 
creation 3-15 , 4-2 
deletion 3-22 , 4-8 
duplication 3-15 , 4-3 
granularity 3-31 
handling 2-2, 2-5, 2-8, 2-9, 4-1 
length 3-31 
listing 3-15 , 4-4 
name 4-2 
owner 3-31, 3-49 
renaming 3-45 , 4-14 
replacement 3-15 , 4-5 
restoring 3-48 
scrolling 4-5 
sequencing 4-7 
structures 1“1, l'~4 
SUBMIT 3-55 , 4-20 
f nodes 3-41, 3-42 , 4-18 
formal parameters 3-57 
FORMAT command 1-7, 3-40, 4-18, 6-30 
F0RMAT$EXCEPTI0N system call 5-8, 6-2, 6-11 


Index-4 



INDEX 


GET$CHAR system call 6-2, 6-13 
GET$CONNECTION$ STATUS system call 6-8, 6-28 
GET$DEFAULT$PREFIX system call 6-8, 6-18, 6-28, 6-45 
GET$EXCEPTION$ HANDLER system call 5-8 
GET$FILE$STATUS system call 6-7, 6-18, 6-27 

GET$INPUT$ CONNECTION system call 5-3, 6-2, 6-14, 6-15, 6-20, 7-1 
GET$INPUT$PATHNAME system call 5-1, 5-3, 6-2, 6-20, 6-56, 7-1 
GET$0UTPUT$ CONNECTION system call 5-3, 5-4, 6-2, 6-22, 6-23, 6-31,6-32, 
7-1 

GET$PARAMETER system call 5-1, 5-6, 6-2, 6-34 , 6-35, 7-1 
GET$TYPE system call 6-8, 6-18, 6-28, 6-45, 6-50, 6-53 
granularity 3-31, 3-41, 3-42 , 4-18 

Human Interface 
commands 3-1 
services 1-2 

software requirements 1-1 
system calls 1~3, 6-2 
type definitions A-1 

I/O processing 5-3, 6-2, 6-14, 6-20, 6-22 
input and output calls 5-2 
interleave factor 3-41 , 4-18 
iSBC 957A/B package 3-21, 3-37, 3-59 
ISIS-II files 1-3, 3-37, 3-59 

keyboard character entries 2-4 
keyword parameters 6-35 

line terminator 6-48, 6-51 
listing formats 1-3 
load module formats 5-8 
L0AD$I0$J0B system call 6-45 
logical device 4-19 
logical names 1-5, 1-7, 2-5, 5-8 

L00KUP$0BJECT system call 6-8, 6-13, 6-18, 6-21, 6-28, 6-33, 6-36, 6-45, 
6-50, 6-53, "6-57 

message processing 5-2, 5-4 , 6-2, 6-11, 6-48, 6-51 

NAMED files 4-18 
named verification 3-33 
NEW LINE key 2-3 
N0JCREATE__FALSE 6-30 
NO TRUNCATE 6-30 


object directory 6-5, 6-6, 

6-13, 

6-15, 

6-21, 

6-24, 

6-32, 

6-35, 6-39 

6-43, 6-49, 6-52, 6-54, 

6-55, 

6-57 





outpath-llst 2-2, 6-38 
output parameters 2-5, 2-8, 

6-4, 

6-13, 

6-14, 

6-20, 

6-22, 

6-31, 6-34 


6-35, 6-38, 6-48, 6-51, 6-56 

OVER preposition 2-6 , 2-8, 4-5, 4-15, 5-4, 5-6, 6-22, 6-31, 6-32 
owner 3-31, 3-49 


parameter 1~1, 2-1, 4-20, 5-1, 5-2, 5-5, 5-9 
parameter parsing 5-5, 6-32, 6-35 
parent directory 4-10, 6-24 
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parsing calls 6-2, 6-56 
pathlists 2-5 

pathname 1-4 , 1-6, 2-2, 2-8, 4-3, 4-9, 4-14, 4-16, 5-7 
PHYSICAL 3-41, 4-18 
physical device 2-5, 2-7, 4-18 
physical verification 3-33 

PHYSICAL$ATTACH$DEVICE system call 6-7, 6-18, 6-27, 6-45 
POINTER definition A-1 
predlct$table 5-6 

preposition 2-2, 5-2, 5-4, 5-5, 6-22, 6-23, 6-29, 6-31, 6-32, 6-34, 
6-35, 6-38 

preposition parameters 2-6 , 2-9, 5-5, 5-6 
program control call 5-5, 6-3, 6-54 
program debugging 3-21 
program directories 1-5 

QUERY parameter 2-2, 2-4 , 4-3, 4-13 
quoted string 2-3, 5-6, 6-36, 6-43 

READ$MOVE system call 6-28, 6-50, 6-53 

RECEIVE$CONTROL system call 6-8, 6-18, 6-28, 6-45, 6-50, 6-53 
RECEIVE$MESSAGE system call 6-8, 6-18, 6-28, 6-45, 6-50, 6-53 
relocatable load format 5-8, 5-9 

RENAME command 2-8, 2-9, 3-44 , 4-5, 4-9, 4-13, 4-14, 4-16 

RESTORE command 3-9, 3-48 

RETURN key 2-2, 2-3, 2-4, 2-7, 2-8 , 5-1 

root directory 4-17 

RUBOUT key 2-8 

SEEK system call 6-27, 6-28, 6-45, 6-50, 6-53 
semicolon character 2-3 

SEND$C0$ RESPONSE system call 6-2, 6-48 , 6-49, 6-52 
SEND$COMMAND system call 5-5, 6-3, 6-4, 6-38, 6-39, 7-1 
SEND$C0NTR0L system call 6-8, 6-18, 6-28, 6-45, 6-50, 6-53 
SEND$EO$RESPONSE system call 6-2, 6-49, 6-51 , 6-52 

SEND$MESSAGE system call 6-8, 6-18, 6-28, 6-45, 6-48, 6-50, 6-51, 6-53 

SET$C0NTR0L$C system call 5-5, 5-8, 6-3, 6-54 

SET$EXCEPTION$ HANDLER system call 5-8 

SET$INTERRUPT system call 6-8, 6-18, 6-28, 6-45 

SET$PARSE$BUFFER system call 6-2, 6-56 


single -stepping 

3-21 



slash separator 

4-10 



SPECIAL system call 6-7, 

6-18, 6-27, 

6-45 

Standard Input 

5-3, 5-4, 

6-2, 6-20 


Standard Output 

5-3, 5-4, 

, 6-2, 6-31, 

6-32 


STRING 6-1, 6-11, 6-14, 6-20, 6-22, 6-31, 6-48, 6-51, 6-56 

STRING$TABLE 5-6, 6-34, 6-35 

SUBMIT command 2-3, 3-55 , 4-20, 6-49, 6-52 

submit file 4-20 

system 

call dictionary 6-2 
clock 3-58 
date 3-20 

program directory 1~2, 5-7 
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TIME command 3-58 

TO preposition 2-6 , 4-4, 4-6, 4-12, 4-14, 4-16, 5-4, 6-22, 6-23, 6-31 

token definition A-1 

TRUNCATE system call 6-27, 6-28 

TRUNCATE$FILE system call 6-28 

type definition A-1 

UNCATALOG$OBJECT system call 6-40, 6-45, 6-54 
UPCOPY command 3-59, 5-9 
User directories 1-6 , 4-8 

verification utility 3-32 
volume 

boundaries 4-16 
formatting 3-40, 4-18 
granularity 3-41, 3-42 
prefix 4-17 
verification 3-32 

WAIT$ INTERRUPT system call 6-8, 6-18, 6-28, 6-45 
WORD 6-1, 6-4 
work directory 1-6 

WRITE system call 6-27, 6-28, 6-50, 6-53 
WRITE$M0VE system call 6-28, 6-50, 6-53 
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